diff options
author | Tristan Gingold <tgingold@free.fr> | 2016-07-14 17:40:32 +0200 |
---|---|---|
committer | Tristan Gingold <tgingold@free.fr> | 2016-07-14 17:40:32 +0200 |
commit | 3e04f0aadc73a45eeba46d4ee3bc5a533b8d4a47 (patch) | |
tree | 44d30624306e10019a22b6cd057530f39118a74a /doc | |
parent | 8db5c10786bca404c5d1e129090ea9fea25531d2 (diff) | |
download | ghdl-3e04f0aadc73a45eeba46d4ee3bc5a533b8d4a47.tar.gz ghdl-3e04f0aadc73a45eeba46d4ee3bc5a533b8d4a47.tar.bz2 ghdl-3e04f0aadc73a45eeba46d4ee3bc5a533b8d4a47.zip |
vpi: add and document new options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/Invoking_GHDL.rst | 103 | ||||
-rw-r--r-- | doc/ghdl.texi | 376 |
2 files changed, 379 insertions, 100 deletions
diff --git a/doc/Invoking_GHDL.rst b/doc/Invoking_GHDL.rst index 13823b9d5..fda18f802 100644 --- a/doc/Invoking_GHDL.rst +++ b/doc/Invoking_GHDL.rst @@ -955,6 +955,109 @@ Display the `GHDL` version and exit:: ghdl --version +VPI build commands +============== + +These commands simplify the compile and the link of a user vpi +module. They are all wrapper: the arguments are in fact a whole +command line that is executed with additional switches. Currently a +unix-like compiler (like `cc`, `gcc` or `clang`) is expected: the additional +switches use their syntax. The only option is `-v` which displays the +command before its execution. + +.. _VPI_compile_command: + +VPI compile command +----------------- + +.. index:: --vpi-compile command + +Add include path to the command and execute it:: + + ghdl --vpi-compile command + +This will execute:: + + command -Ixxx/include + +For example:: + + ghdl --vpi-compile gcc -c vpi1.c + +executes:: + + gcc -c vpi1.c -fPIC -Ixxx/include + +.. _VPI_link_command: + +VPI link command +-------------- + +.. index:: --vpi-link command + +Add library path and name to the command and execute it:: + + ghdl --vpi-link command + +This will execute:: + + command -Lxxx/lib -lghdlvpi + +For example:: + + ghdl --vpi-link gcc -o vpi1.vpi vpi1.o + +executes:: + + gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi + + +.. _VPI_cflags_command: + +VPI cflags command +---------------- + +.. index:: --vpi-cflags command + +Display flags added by :option:`--vpi-compile`:: + + ghdl --vpi-cflags + + +.. _VPI_ldflags_command: + +VPI ldflags command +----------------- + +.. index:: --vpi-ldflags command + +Display flags added by :option:`--vpi-link`:: + + ghdl --vpi-ldflags + +.. _VPI_include_dir_command: + +VPI include dir command +-------------------- + +.. index:: --vpi-include-dir command + +Display the include directory added by the compile flags:: + + ghdl --vpi-include-dir + +.. _VPI_library_dir_command: + +VPI library dir command +------------------- + +.. index:: --vpi-library-dir command + +Display the library directory added by the link flags:: + + ghdl --vpi-library-dir + + Installation Directory ====================== diff --git a/doc/ghdl.texi b/doc/ghdl.texi index 15c4b3a1c..e0912f2a7 100644 --- a/doc/ghdl.texi +++ b/doc/ghdl.texi @@ -3,7 +3,7 @@ @setfilename GHDL.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 1.3.1.@* +@*Generated by Sphinx 1.3.5.@* @end ifinfo @settitle GHDL Documentation @defindex ge @@ -21,7 +21,7 @@ @copying @quotation -GHDL 0.33, November 24, 2015 +GHDL 0.33, July 14, 2016 Tristan Gingold @@ -93,6 +93,7 @@ Invoking GHDL * Cross-reference command:: * File commands:: * Misc commands:: +* VPI build commands:: * Installation Directory:: * IEEE library pitfalls:: * IEEE math packages:: @@ -137,6 +138,15 @@ Misc commands * Disp standard command:: * Version command:: +VPI build commands + +* VPI compile command:: +* VPI link command:: +* VPI cflags command:: +* VPI ldflags command:: +* VPI include dir command:: +* VPI library dir command:: + Simulation and runtime * Simulation options:: @@ -326,11 +336,11 @@ $ ghdl -e hello_world @end example The @code{-e} option means @emph{elaborate}. With this option, @cite{GHDL} -creates code in order to elaborate a design, with the @code{hello} +creates code in order to elaborate a design, with the @code{hello_world} entity at the top of the hierarchy. -On GNU/Linux, the result is an executable program called @code{hello} -which can be run: +On GNU/Linux, if you have enabled the GCC backend during the compilation of @cite{GHDL}, +an executable program called @code{hello_world} which can be run is generated: @example $ ghdl -r hello_world @@ -342,7 +352,8 @@ or directly: $ ./hello_world @end example -On Windows, no file is created. The simulation is launched using this command: +On Windows or if the GCC backend was not enabled, no file is created. +The simulation is launched using this command: @example > ghdl -r hello_world @@ -444,7 +455,7 @@ begin assert s = patterns(i).s report "bad sum value" severity error; assert co = patterns(i).co - report "bad carray out value" severity error; + report "bad carry out value" severity error; end loop; assert false report "end of test" severity note; -- Wait forever; this will finish the simulation. @@ -553,7 +564,7 @@ $ cp test_loop.out dlx.out And you can run the test suite: @example -$ ghdl -r dlx_test_behaviour +$ ghdl -r --workdir=work dlx_test_behaviour @end example The test bench monitors the bus and displays each instruction executed. @@ -570,7 +581,7 @@ test bench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs: @example -$ ghdl -r dlx_test_behaviour --assert-level=note +$ ghdl -r --workdir=work dlx_test_behaviour --assert-level=note @end example With this option, the program stops just after the previous message: @@ -656,6 +667,7 @@ no option is allowed after a filename or a unit name. * Cross-reference command:: * File commands:: * Misc commands:: +* VPI build commands:: * Installation Directory:: * IEEE library pitfalls:: * IEEE math packages:: @@ -689,9 +701,9 @@ The mostly used commands of GHDL are those to analyze and elaborate a design. @geindex analysis -@geindex *-a* command +@geindex -a command -Analyze one or severals files: +Analyze one or several files: @example ghdl -a [options...] file... @@ -718,7 +730,7 @@ ghdl -a -g my_design.vhdl @geindex elaboration -@geindex *-e* command +@geindex -e command Elaborate a design: @@ -726,10 +738,11 @@ Elaborate a design: ghdl -e [options..] primary_unit [secondary_unit] @end example -On GNU/Linux the elaboration command creates an executable -containing the code of the @cite{VHDL} sources, the elaboration code -and simulation code to execute a design hierarchy. On Windows this -command elaborates the design but does not generate anything. +On GNU/Linux, if the GCC backend was enabled during the compilation of @cite{GHDL}, +the elaboration command creates an executable containing the code of the @cite{VHDL} +sources, the elaboration code and simulation code to execute a design hierarchy. +On Windows or if the GCC backend was not enabled, this command elaborates the design +but does not generate anything. The elaboration command is selected with @code{-e} switch, and must be followed by either: @@ -781,7 +794,7 @@ run command. @geindex run -@geindex *-r* command +@geindex -r command Run (or simulate) a design: @@ -823,7 +836,7 @@ See @ref{19,,Simulation and runtime}, for details on options. @geindex elaborate and run -@geindex *--elab-run* command +@geindex --elab-run command Elaborate and then simulate a design unit: @@ -841,7 +854,7 @@ followed by the run command (see @ref{17,,Run command}). @geindex binding -@geindex *--bind* command +@geindex --bind command Bind a design unit and prepare the link step: @@ -862,7 +875,7 @@ command should be used only when the main entry point is not ghdl. @geindex linking -@geindex *--link* command +@geindex --link command Link an already bound design unit: @@ -880,7 +893,7 @@ equivalent to the bind command followed by the link command. @subsection List link command -@geindex *--list-link* command +@geindex --list-link command Display files which will be linked: @@ -901,7 +914,7 @@ intended to add object files in a link of a foreign program. @geindex checking syntax -@geindex *-s* command +@geindex -s command Analyze files but do not generate code: @@ -919,7 +932,7 @@ the library. @geindex Analyze and elaborate command -@geindex *-c* command +@geindex -c command Analyze files and elaborate them at the same time. @@ -1089,7 +1102,9 @@ your design, and during elaboration. @deffn {Option} @w{-}P<DIRECTORY> Add @cite{DIRECTORY} to the end of the list of directories to be searched for -library files. +library files. A library is searched in @cite{DIRECTORY} and also in +@cite{DIRECTORY/LIB/vVV} (where @cite{LIB} is the name of the library and @cite{VV} +the vhdl standard). The @cite{WORK} library is always searched in the path specified by the @code{--workdir=} option, or in the current directory if the latter @@ -1370,7 +1385,7 @@ due to dependencies. GHDL has a few commands to rebuild a design. @geindex importing files -@geindex *-i* command +@geindex -i command Add files in the work design library: @@ -1400,7 +1415,7 @@ See @ref{48,,Make command}, to actually build the design. @geindex make -@geindex *-m* command +@geindex -m command Analyze automatically outdated files and elaborate a design: @@ -1416,7 +1431,7 @@ all outdated files. A file may be outdated because it has been modified the file depends on a unit which is outdated. This rule is of course recursive. -With the @code{-b} (bind only) option, GHDL will stop before the final linking +With the @@code@{-b@} (bind only) option, GHDL will stop before the final linking step. This is useful when the main entry point is not GHDL and you're linking GHDL object files into a foreign program. @@ -1454,7 +1469,7 @@ such a case, re-run the make command of GHDL. @subsection Generate Makefile command -@geindex *--gen-makefile* command +@geindex --gen-makefile command Generate a Makefile to build a design unit: @@ -1488,16 +1503,19 @@ GHDL has a few commands which act on a library. @geindex displaying library -@geindex *-d* command +@geindex --dir command + +@c option::--dir Display the name of the units contained in a design library: @example -ghdl -d [options] +ghdl --dir [options] [libs] @end example -The directory command, selected with the @cite{-d} command line argument -displays the content of the work design library. All options are +The directory command, selected with the @cite{--dir} command line argument +displays the content of the design libraries (by default the +@code{work} library). All options are allowed, but only a few are meaningful: @code{--work=NAME}, @code{--workdir=PATH} and @code{--std=VER}. @@ -1508,7 +1526,7 @@ allowed, but only a few are meaningful: @code{--work=NAME}, @geindex cleaning -@geindex *--clean* command +@geindex --clean command Remove object and executable files but keep the library: @@ -1529,7 +1547,7 @@ clean up. @geindex cleaning all -@geindex *--remove* command +@geindex --remove command Do like the clean command but remove the library too: @@ -1548,7 +1566,7 @@ known anymore by GHDL. @geindex copying library -@geindex *--copy* command +@geindex --copy command Make a local copy of an existing library: @@ -1636,7 +1654,7 @@ files, therefore, they work even if a file has semantic errors. @subsection Pretty print command -@geindex *--pp-html* command +@geindex --pp-html command @geindex pretty printing @@ -1666,7 +1684,7 @@ See @ref{55,,Cross-reference command}, for more details about this CSS file. @subsection Find command -@geindex *-f* command +@geindex -f command Display the name of the design units in files: @@ -1683,7 +1701,7 @@ design hierarchy. @subsection Chop command -@geindex *--chop* command +@geindex --chop command Chop (or split) files at design unit: @@ -1715,7 +1733,7 @@ reduced too. @subsection Lines command -@geindex *--lines* command +@geindex --lines command Display on the standard output lines of files preceded by line number: @@ -1723,7 +1741,7 @@ Display on the standard output lines of files preceded by line number: ghdl --lines files @end example -@node Misc commands,Installation Directory,File commands,Invoking GHDL +@node Misc commands,VPI build commands,File commands,Invoking GHDL @anchor{Invoking_GHDL misc-commands}@anchor{5b} @section Misc commands @@ -1743,9 +1761,9 @@ There are a few GHDL commands which are seldom useful. @subsection Help command -@geindex *-h* command +@geindex -h command -@geindex *--help* command +@geindex --help command Display (on the standard output) a short description of the all the commands available. If the help switch is followed by a command switch, then options @@ -1762,7 +1780,7 @@ ghdl -h command @subsection Disp config command -@geindex *--disp-config* command +@geindex --disp-config command @geindex display configuration @@ -1779,7 +1797,7 @@ This may be useful to track installation errors. @subsection Disp standard command -@geindex *--disp-standard* command +@geindex --disp-standard command @geindex display ;samp;`std.standard` @@ -1794,7 +1812,7 @@ ghdl --disp-standard [options] @subsection Version command -@geindex *--version* command +@geindex --version command @geindex version @@ -1804,8 +1822,144 @@ Display the @cite{GHDL} version and exit: ghdl --version @end example -@node Installation Directory,IEEE library pitfalls,Misc commands,Invoking GHDL -@anchor{Invoking_GHDL installation-directory}@anchor{62} +@node VPI build commands,Installation Directory,Misc commands,Invoking GHDL +@anchor{Invoking_GHDL vpi-build-commands}@anchor{62} +@section VPI build commands + + +These commands simplify the compile and the link of a user vpi +module. They are all wrapper: the arguments are in fact a whole +command line that is executed with additional switches. Currently a +unix-like compiler (like @cite{cc}, @cite{gcc} or @cite{clang}) is expected: the additional +switches use their syntax. The only option is @cite{-v} which displays the +command before its execution. + +@menu +* VPI compile command:: +* VPI link command:: +* VPI cflags command:: +* VPI ldflags command:: +* VPI include dir command:: +* VPI library dir command:: + +@end menu + +@node VPI compile command,VPI link command,,VPI build commands +@anchor{Invoking_GHDL vpi-compile-command}@anchor{63}@anchor{Invoking_GHDL id16}@anchor{64} +@subsection VPI compile command + + +@geindex --vpi-compile command + +Add include path to the command and execute it: + +@example +ghdl --vpi-compile command +@end example + +This will execute: + +@example +command -Ixxx/include +@end example + +For example: + +@example +ghdl --vpi-compile gcc -c vpi1.c +@end example + +executes: + +@example +gcc -c vpi1.c -fPIC -Ixxx/include +@end example + +@node VPI link command,VPI cflags command,VPI compile command,VPI build commands +@anchor{Invoking_GHDL vpi-link-command}@anchor{65}@anchor{Invoking_GHDL id17}@anchor{66} +@subsection VPI link command + + +@geindex --vpi-link command + +Add library path and name to the command and execute it: + +@example +ghdl --vpi-link command +@end example + +This will execute: + +@example +command -Lxxx/lib -lghdlvpi +@end example + +For example: + +@example +ghdl --vpi-link gcc -o vpi1.vpi vpi1.o +@end example + +executes: + +@example +gcc -o vpi1.vpi vpi1.o --shared -Lxxx/lib -lghdlvpi +@end example + +@node VPI cflags command,VPI ldflags command,VPI link command,VPI build commands +@anchor{Invoking_GHDL id18}@anchor{67}@anchor{Invoking_GHDL vpi-cflags-command}@anchor{68} +@subsection VPI cflags command + + +@geindex --vpi-cflags command + +Display flags added by @code{--vpi-compile}: + +@example +ghdl --vpi-cflags +@end example + +@node VPI ldflags command,VPI include dir command,VPI cflags command,VPI build commands +@anchor{Invoking_GHDL id19}@anchor{69}@anchor{Invoking_GHDL vpi-ldflags-command}@anchor{6a} +@subsection VPI ldflags command + + +@geindex --vpi-ldflags command + +Display flags added by @code{--vpi-link}: + +@example +ghdl --vpi-ldflags +@end example + +@node VPI include dir command,VPI library dir command,VPI ldflags command,VPI build commands +@anchor{Invoking_GHDL vpi-include-dir-command}@anchor{6b}@anchor{Invoking_GHDL id20}@anchor{6c} +@subsection VPI include dir command + + +@geindex --vpi-include-dir command + +Display the include directory added by the compile flags: + +@example +ghdl --vpi-include-dir +@end example + +@node VPI library dir command,,VPI include dir command,VPI build commands +@anchor{Invoking_GHDL vpi-library-dir-command}@anchor{6d}@anchor{Invoking_GHDL id21}@anchor{6e} +@subsection VPI library dir command + + +@geindex --vpi-library-dir command + +Display the library directory added by the link flags: + +@example +ghdl --vpi-library-dir +@end example + +@node Installation Directory,IEEE library pitfalls,VPI build commands,Invoking GHDL +@anchor{Invoking_GHDL installation-directory}@anchor{6f} @section Installation Directory @@ -1833,7 +1987,7 @@ value of the @code{HKLMSoftwareGhdlInstall_Dir} registry entry on Windows. You should use the @code{--disp-config} command (@ref{5e,,Disp config command} for details) to disp and debug installation problems. @node IEEE library pitfalls,IEEE math packages,Installation Directory,Invoking GHDL -@anchor{Invoking_GHDL ieee-library-pitfalls}@anchor{e}@anchor{Invoking_GHDL id16}@anchor{63} +@anchor{Invoking_GHDL ieee-library-pitfalls}@anchor{e}@anchor{Invoking_GHDL id22}@anchor{70} @section IEEE library pitfalls @@ -1968,7 +2122,7 @@ end good; @end example @node IEEE math packages,,IEEE library pitfalls,Invoking GHDL -@anchor{Invoking_GHDL ieee-math-packages}@anchor{64} +@anchor{Invoking_GHDL ieee-math-packages}@anchor{71} @section IEEE math packages @@ -1981,7 +2135,7 @@ The @code{ieee} math packages (@code{math_real} and the @cite{IEEE} standard. @node Simulation and runtime,GHDL implementation of VHDL,Invoking GHDL,Top -@anchor{Simulation_and_runtime simulation-and-runtime}@anchor{19}@anchor{Simulation_and_runtime doc}@anchor{65}@anchor{Simulation_and_runtime id1}@anchor{66} +@anchor{Simulation_and_runtime simulation-and-runtime}@anchor{19}@anchor{Simulation_and_runtime doc}@anchor{72}@anchor{Simulation_and_runtime id1}@anchor{73} @chapter Simulation and runtime @@ -1992,7 +2146,7 @@ the @cite{IEEE} standard. @end menu @node Simulation options,Debugging VHDL programs,,Simulation and runtime -@anchor{Simulation_and_runtime simulation-options}@anchor{b}@anchor{Simulation_and_runtime id2}@anchor{67} +@anchor{Simulation_and_runtime simulation-options}@anchor{b}@anchor{Simulation_and_runtime id2}@anchor{74} @section Simulation options @@ -2012,11 +2166,11 @@ simulation completes, or @code{EXIT_FAILURE} (1) in case of error (assertion failure, overflow or any constraint error). Here is the list of the most useful options. Some debugging options are -also available, but not described here. The @ref{68,,--help} options lists +also available, but not described here. The @ref{75,,--help} options lists all options available, including the debugging one. @geindex command line option; --assert-level=<LEVEL> -@anchor{Simulation_and_runtime cmdoption--assert-level}@anchor{69} +@anchor{Simulation_and_runtime cmdoption--assert-level}@anchor{76} @deffn {Option} @w{-}@w{-}assert@w{-}level=<LEVEL> Select the assertion level at which an assertion violation stops the @@ -2037,7 +2191,7 @@ simulation. @end deffn @geindex command line option; --ieee-asserts=<POLICY> -@anchor{Simulation_and_runtime cmdoption--ieee-asserts}@anchor{6a} +@anchor{Simulation_and_runtime cmdoption--ieee-asserts}@anchor{77} @deffn {Option} @w{-}@w{-}ieee@w{-}asserts=<POLICY> Select how the assertions from @code{ieee} units are @@ -2050,7 +2204,7 @@ This option can be useful to avoid assertion message from @end deffn @geindex command line option; --stop-time=<TIME> -@anchor{Simulation_and_runtime cmdoption--stop-time}@anchor{6b} +@anchor{Simulation_and_runtime cmdoption--stop-time}@anchor{78} @deffn {Option} @w{-}@w{-}stop@w{-}time=<TIME> Stop the simulation after @code{TIME}. @code{TIME} is expressed as a time @@ -2066,7 +2220,7 @@ $ ./my_design --stop-time=ps @end deffn @geindex command line option; --stop-delta=<N> -@anchor{Simulation_and_runtime cmdoption--stop-delta}@anchor{6c} +@anchor{Simulation_and_runtime cmdoption--stop-delta}@anchor{79} @deffn {Option} @w{-}@w{-}stop@w{-}delta=<N> Stop the simulation after @cite{N} delta cycles in the same current time. @@ -2075,14 +2229,14 @@ Stop the simulation after @cite{N} delta cycles in the same current time. @end deffn @geindex command line option; --disp-time -@anchor{Simulation_and_runtime cmdoption--disp-time}@anchor{6d} +@anchor{Simulation_and_runtime cmdoption--disp-time}@anchor{7a} @deffn {Option} @w{-}@w{-}disp@w{-}time Display the time and delta cycle number as simulation advances. @end deffn @geindex command line option; --disp-tree[=<KIND>] -@anchor{Simulation_and_runtime cmdoption--disp-tree}@anchor{6e} +@anchor{Simulation_and_runtime cmdoption--disp-tree}@anchor{7b} @deffn {Option} @w{-}@w{-}disp@w{-}tree[=<KIND>] @geindex display design hierarchy @@ -2115,21 +2269,28 @@ If @cite{KIND} is not specified, the hierarchy is displayed with the @end deffn @geindex command line option; --no-run -@anchor{Simulation_and_runtime cmdoption--no-run}@anchor{6f} +@anchor{Simulation_and_runtime cmdoption--no-run}@anchor{7c} @deffn {Option} @w{-}@w{-}no@w{-}run Do not simulate, only elaborate. This may be used with -@ref{6e,,--disp-tree} to display the tree without simulating the whole +@ref{7b,,--disp-tree} to display the tree without simulating the whole design. @end deffn +@geindex command line option; --unbuffered +@anchor{Simulation_and_runtime cmdoption--unbuffered}@anchor{7d} +@deffn {Option} @w{-}@w{-}unbuffered + +Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO). +@end deffn + @geindex command line option; --vcd=<FILENAME> @anchor{Simulation_and_runtime cmdoption--vcd}@anchor{c} @deffn {Option} @w{-}@w{-}vcd=<FILENAME> @end deffn @geindex command line option; --vcdgz=<FILENAME> -@anchor{Simulation_and_runtime cmdoption--vcdgz}@anchor{70} +@anchor{Simulation_and_runtime cmdoption--vcdgz}@anchor{7e} @deffn {Option} @w{-}@w{-}vcdgz=<FILENAME> @geindex vcd @@ -2143,7 +2304,7 @@ values before each non-delta cycle. If @cite{FILENAME} is @code{-}, then the standard output is used, otherwise a file is created or overwritten. -The @ref{70,,--vcdgz} option is the same as the @emph{--vcd} option, +The @ref{7e,,--vcdgz} option is the same as the @emph{--vcd} option, but the output is compressed using the @cite{zlib} (@cite{gzip} compression). However, you can't use the @code{-} filename. Furthermore, only one VCD file can be written. @@ -2192,11 +2353,11 @@ dumped, which can generate big files. It is very unfortunate there is no standard or well-known wave file format supporting VHDL types. If you are aware of such a free format, -please mail me (@ref{71,,Reporting bugs}). +please mail me (@ref{7f,,Reporting bugs}). @end deffn @geindex command line option; --fst=<FILENAME> -@anchor{Simulation_and_runtime cmdoption--fst}@anchor{72} +@anchor{Simulation_and_runtime cmdoption--fst}@anchor{80} @deffn {Option} @w{-}@w{-}fst=<FILENAME> Write the waveforms into a @cite{fst}, that can be displayed by @@ -2205,7 +2366,7 @@ Write the waveforms into a @cite{fst}, that can be displayed by @end deffn @geindex command line option; --wave=<FILENAME> -@anchor{Simulation_and_runtime cmdoption--wave}@anchor{73} +@anchor{Simulation_and_runtime cmdoption--wave}@anchor{81} @deffn {Option} @w{-}@w{-}wave=<FILENAME> Write the waveforms into a @cite{ghw} (GHdl Waveform) file. Currently, all @@ -2218,8 +2379,17 @@ It may change slightly. The @code{gtkwave} tool can read the GHW files. Contrary to VCD files, any VHDL type can be dumped into a GHW file. @end deffn +@geindex command line option; --psl-report=<FILENAME> +@anchor{Simulation_and_runtime cmdoption--psl-report}@anchor{82} +@deffn {Option} @w{-}@w{-}psl@w{-}report=<FILENAME> + +Write a report for PSL assertions and coverage at the end of +simulation. The file is written using the JSON format, but still +being human readable. +@end deffn + @geindex command line option; --sdf=<PATH>=<FILENAME> -@anchor{Simulation_and_runtime cmdoption--sdf}@anchor{74} +@anchor{Simulation_and_runtime cmdoption--sdf}@anchor{83} @deffn {Option} @w{-}@w{-}sdf=<PATH>=<FILENAME> Do VITAL annotation on @cite{PATH} with SDF file @code{FILENAME}. @@ -2241,18 +2411,18 @@ If the option contains a type of delay, that is @code{min=}, typical or maximum values. If the option does not contain a type of delay, the annotator use the typical delay. -See @ref{75,,Backannotation}, for more details. +See @ref{84,,Backannotation}, for more details. @end deffn @geindex command line option; --help -@anchor{Simulation_and_runtime cmdoption--help}@anchor{68} +@anchor{Simulation_and_runtime cmdoption--help}@anchor{75} @deffn {Option} @w{-}@w{-}help Display a short description of the options accepted by the runtime library. @end deffn @node Debugging VHDL programs,,Simulation options,Simulation and runtime -@anchor{Simulation_and_runtime debugging-vhdl-programs}@anchor{76} +@anchor{Simulation_and_runtime debugging-vhdl-programs}@anchor{85} @section Debugging VHDL programs @@ -2282,7 +2452,7 @@ When the breakpoint is hit, use the @cite{where} or @cite{bt} command to display the stack frames. @node GHDL implementation of VHDL,GHDL implementation of VITAL,Simulation and runtime,Top -@anchor{GHDL_implementation_of_VHDL doc}@anchor{77}@anchor{GHDL_implementation_of_VHDL ghdl-implementation-of-vhdl}@anchor{78} +@anchor{GHDL_implementation_of_VHDL doc}@anchor{86}@anchor{GHDL_implementation_of_VHDL ghdl-implementation-of-vhdl}@anchor{87} @chapter GHDL implementation of VHDL @@ -2300,7 +2470,7 @@ This chapter describes several implementation defined aspect of VHDL in GHDL. @end menu @node VHDL standards,PSL implementation,,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL vhdl-standards}@anchor{29}@anchor{GHDL_implementation_of_VHDL id1}@anchor{79} +@anchor{GHDL_implementation_of_VHDL vhdl-standards}@anchor{29}@anchor{GHDL_implementation_of_VHDL id1}@anchor{88} @section VHDL standards @@ -2324,6 +2494,8 @@ This chapter describes several implementation defined aspect of VHDL in GHDL. @geindex v02 +@geindex v08 + This is very unfortunate, but there are many versions of the VHDL language, and they aren't backward compatible. @@ -2370,6 +2542,9 @@ Minors corrections were added by the 2002 revision of the VHDL standard. This revision is not fully backward compatible with VHDL-00 since, for example, the value of the @cite{'instance_name} attribute has slightly changed. +The latest version is 2008. Many features have been added, and GHDL +doesn't implement all of them. + You can select the VHDL standard expected by GHDL with the @code{--std=VER} option, where @code{VER} is one of the left column of the table below: @@ -2414,11 +2589,12 @@ Select VHDL-2002 standard Select VHDL-2008 standard (partially implemented). @end table -You cannot mix VHDL-87 and VHDL-93 units. A design hierarchy must have been -completely analyzed using either the 87 or the 93 version of the VHDL standard. +The 93, 93c, 00 and 02 standards are considered as compatible: you can +elaborate a design mixing these standards. However, 87, 93 and 08 are +not compatible. @node PSL implementation,Source representation,VHDL standards,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL id2}@anchor{7a}@anchor{GHDL_implementation_of_VHDL psl-implementation}@anchor{2f} +@anchor{GHDL_implementation_of_VHDL id2}@anchor{89}@anchor{GHDL_implementation_of_VHDL psl-implementation}@anchor{2f} @section PSL implementation @@ -2458,7 +2634,7 @@ Of course only the simple subset of PSL is allowed. Currently the built-in functions are not implemented. @node Source representation,Library database,PSL implementation,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL source-representation}@anchor{7b} +@anchor{GHDL_implementation_of_VHDL source-representation}@anchor{8a} @section Source representation @@ -2484,7 +2660,7 @@ analyzed). Therefore, if you delete or modify a source file of a unit analyzed, GHDL will refuse to use it. @node Library database,Top entity,Source representation,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL library-database}@anchor{7c}@anchor{GHDL_implementation_of_VHDL id3}@anchor{7d} +@anchor{GHDL_implementation_of_VHDL library-database}@anchor{8b}@anchor{GHDL_implementation_of_VHDL id3}@anchor{8c} @section Library database @@ -2494,8 +2670,8 @@ changed with the @code{--work=NAME} option of GHDL. To keep the list of design units in a design library, GHDL creates library files. The name of these files is @code{NAME-objVER.cf}, where -@cite{NAME} is the name of the library, and @cite{VER} the VHDL version (87 -or 93) used to analyze the design units. +@cite{NAME} is the name of the library, and @cite{VER} the VHDL version (87, +93 or 08) used to analyze the design units. You don't have to know how to read a library file. You can display it using the @emph{-d} of @cite{ghdl}. The file contains the name of the @@ -2504,7 +2680,7 @@ design units, as well as the location and the dependencies. The format may change with the next version of GHDL. @node Top entity,Using vendor libraries,Library database,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL top-entity}@anchor{16}@anchor{GHDL_implementation_of_VHDL id4}@anchor{7e} +@anchor{GHDL_implementation_of_VHDL top-entity}@anchor{16}@anchor{GHDL_implementation_of_VHDL id4}@anchor{8d} @section Top entity @@ -2523,7 +2699,7 @@ The ports type must be constrained. @end itemize @node Using vendor libraries,Interfacing to other languages,Top entity,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL using-vendor-libraries}@anchor{7f} +@anchor{GHDL_implementation_of_VHDL using-vendor-libraries}@anchor{8e} @section Using vendor libraries @@ -2537,7 +2713,7 @@ restrictions by using the @code{--std=93c}, @ref{2c,,-fexplicit}, @ref{2d,,-frelaxed-rules} and @code{--warn-no-vital-generic}. @node Interfacing to other languages,,Using vendor libraries,GHDL implementation of VHDL -@anchor{GHDL_implementation_of_VHDL interfacing-to-other-languages}@anchor{80} +@anchor{GHDL_implementation_of_VHDL interfacing-to-other-languages}@anchor{8f} @section Interfacing to other languages @@ -2567,7 +2743,7 @@ You can define a subprogram in a foreign language (such as @cite{C} or @end menu @node Foreign declarations,Restrictions on foreign declarations,,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL foreign-declarations}@anchor{81} +@anchor{GHDL_implementation_of_VHDL foreign-declarations}@anchor{90} @subsection Foreign declarations @@ -2606,7 +2782,7 @@ upper-case keyword followed by one or more blanks). The linkage name of the subprogram follows. @node Restrictions on foreign declarations,Linking with foreign object files,Foreign declarations,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL restrictions-on-foreign-declarations}@anchor{82}@anchor{GHDL_implementation_of_VHDL id5}@anchor{83} +@anchor{GHDL_implementation_of_VHDL restrictions-on-foreign-declarations}@anchor{91}@anchor{GHDL_implementation_of_VHDL id5}@anchor{92} @subsection Restrictions on foreign declarations @@ -2661,7 +2837,7 @@ Files are represented by a 32 bits word, which corresponds to an index in a table. @node Linking with foreign object files,Starting a simulation from a foreign program,Restrictions on foreign declarations,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL id6}@anchor{84}@anchor{GHDL_implementation_of_VHDL linking-with-foreign-object-files}@anchor{85} +@anchor{GHDL_implementation_of_VHDL id6}@anchor{93}@anchor{GHDL_implementation_of_VHDL linking-with-foreign-object-files}@anchor{94} @subsection Linking with foreign object files @@ -2679,7 +2855,7 @@ library. Note the @code{c} library is always linked with an executable. @node Starting a simulation from a foreign program,Linking with Ada,Linking with foreign object files,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL id7}@anchor{86}@anchor{GHDL_implementation_of_VHDL starting-a-simulation-from-a-foreign-program}@anchor{87} +@anchor{GHDL_implementation_of_VHDL id7}@anchor{95}@anchor{GHDL_implementation_of_VHDL starting-a-simulation-from-a-foreign-program}@anchor{96} @subsection Starting a simulation from a foreign program @@ -2706,11 +2882,11 @@ This function must be called once, and returns 0 at the end of the simulation. In case of failure, this function does not return. This has to be fixed. @node Linking with Ada,Using GRT from Ada,Starting a simulation from a foreign program,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL linking-with-ada}@anchor{88}@anchor{GHDL_implementation_of_VHDL id8}@anchor{89} +@anchor{GHDL_implementation_of_VHDL linking-with-ada}@anchor{97}@anchor{GHDL_implementation_of_VHDL id8}@anchor{98} @subsection Linking with Ada -As explained previously in @ref{87,,Starting a simulation from a foreign program}, +As explained previously in @ref{96,,Starting a simulation from a foreign program}, you can start a simulation from an @cite{Ada} program. However the build process is not trivial: you have to elaborate your @cite{Ada} program and your @cite{VHDL} design. @@ -2737,7 +2913,7 @@ $ gnatmake my_prog -largs `ghdl --list-link design` @end example @node Using GRT from Ada,,Linking with Ada,Interfacing to other languages -@anchor{GHDL_implementation_of_VHDL using-grt-from-ada}@anchor{8a} +@anchor{GHDL_implementation_of_VHDL using-grt-from-ada}@anchor{99} @subsection Using GRT from Ada @@ -2837,7 +3013,7 @@ Root instance name: counter @end example @node GHDL implementation of VITAL,Flaws and bugs report,GHDL implementation of VHDL,Top -@anchor{GHDL_implementation_of_VITAL ghdl-implementation-of-vital}@anchor{8b}@anchor{GHDL_implementation_of_VITAL doc}@anchor{8c} +@anchor{GHDL_implementation_of_VITAL ghdl-implementation-of-vital}@anchor{9a}@anchor{GHDL_implementation_of_VITAL doc}@anchor{9b} @chapter GHDL implementation of VITAL @@ -2859,7 +3035,7 @@ really in a preliminary stage. Do not expect too much of it as now. @end menu @node VITAL packages,VHDL restrictions for VITAL,,GHDL implementation of VITAL -@anchor{GHDL_implementation_of_VITAL vital-packages}@anchor{2b}@anchor{GHDL_implementation_of_VITAL id1}@anchor{8d} +@anchor{GHDL_implementation_of_VITAL vital-packages}@anchor{2b}@anchor{GHDL_implementation_of_VITAL id1}@anchor{9c} @section VITAL packages @@ -2877,7 +3053,7 @@ the VHDL 1993 standard (a few functions are made pure and a few one impure). @node VHDL restrictions for VITAL,Backannotation,VITAL packages,GHDL implementation of VITAL -@anchor{GHDL_implementation_of_VITAL id2}@anchor{8e}@anchor{GHDL_implementation_of_VITAL vhdl-restrictions-for-vital}@anchor{32} +@anchor{GHDL_implementation_of_VITAL id2}@anchor{9d}@anchor{GHDL_implementation_of_VITAL vhdl-restrictions-for-vital}@anchor{32} @section VHDL restrictions for VITAL @@ -2900,7 +3076,7 @@ checks of VITAL restrictions with the @emph{--no-vital-checks}. Even when restrictions are not checked, SDF annotation can be performed. @node Backannotation,Negative constraint calculation,VHDL restrictions for VITAL,GHDL implementation of VITAL -@anchor{GHDL_implementation_of_VITAL backannotation}@anchor{75}@anchor{GHDL_implementation_of_VITAL id3}@anchor{8f} +@anchor{GHDL_implementation_of_VITAL backannotation}@anchor{84}@anchor{GHDL_implementation_of_VITAL id3}@anchor{9e} @section Backannotation @@ -2929,7 +3105,7 @@ just a proof of concept. Features will be added with the following GHDL release. @node Negative constraint calculation,,Backannotation,GHDL implementation of VITAL -@anchor{GHDL_implementation_of_VITAL negative-constraint-calculation}@anchor{90} +@anchor{GHDL_implementation_of_VITAL negative-constraint-calculation}@anchor{9f} @section Negative constraint calculation @@ -2941,7 +3117,7 @@ GHDL does not do negative constraint calculation. It fails to handle models with negative constraint. I hope to be able to add this phase soon. @node Flaws and bugs report,Copyrights,GHDL implementation of VITAL,Top -@anchor{Flaws_and_bugs_report doc}@anchor{91}@anchor{Flaws_and_bugs_report flaws-and-bugs-report}@anchor{92} +@anchor{Flaws_and_bugs_report doc}@anchor{a0}@anchor{Flaws_and_bugs_report flaws-and-bugs-report}@anchor{a1} @chapter Flaws and bugs report @@ -2949,7 +3125,7 @@ Despite all the testing and already reported issues, you can find bugs or propose enhancements. @quotation -@anchor{Flaws_and_bugs_report reporting-bugs}@anchor{71} +@anchor{Flaws_and_bugs_report reporting-bugs}@anchor{7f} @end quotation @menu @@ -2959,7 +3135,7 @@ or propose enhancements. @end menu @node Reporting bugs,Future improvements,,Flaws and bugs report -@anchor{Flaws_and_bugs_report id1}@anchor{93} +@anchor{Flaws_and_bugs_report id1}@anchor{a2} @section Reporting bugs @@ -3027,7 +3203,7 @@ anything else that you think would be helpful. @end itemize @node Future improvements,,Reporting bugs,Flaws and bugs report -@anchor{Flaws_and_bugs_report future-improvements}@anchor{94} +@anchor{Flaws_and_bugs_report future-improvements}@anchor{a3} @section Future improvements @@ -3059,7 +3235,7 @@ VITAL acceleration @end itemize @node Copyrights,Indices and tables,Flaws and bugs report,Top -@anchor{Copyrights copyrights}@anchor{95}@anchor{Copyrights doc}@anchor{96} +@anchor{Copyrights copyrights}@anchor{a4}@anchor{Copyrights doc}@anchor{a5} @chapter Copyrights @@ -3102,10 +3278,10 @@ As a consequence of the runtime copyright, you may not be allowed to distribute an executable produced by @cite{GHDL} without the VHDL sources. To my mind, this is not a real restriction, since there is no points in distributing VHDL executable. Please, send a comment -(@ref{71,,Reporting bugs}) if you don't like this policy. +(@ref{7f,,Reporting bugs}) if you don't like this policy. @node Indices and tables,Index,Copyrights,Top -@anchor{index indices-and-tables}@anchor{97} +@anchor{index indices-and-tables}@anchor{a6} @unnumbered Indices and tables |