From 3e04f0aadc73a45eeba46d4ee3bc5a533b8d4a47 Mon Sep 17 00:00:00 2001 From: Tristan Gingold Date: Thu, 14 Jul 2016 17:40:32 +0200 Subject: vpi: add and document new options --- doc/Invoking_GHDL.rst | 103 ++++++++++++++ doc/ghdl.texi | 376 ++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 379 insertions(+), 100 deletions(-) (limited to 'doc') 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 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= -@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= Select the assertion level at which an assertion violation stops the @@ -2037,7 +2191,7 @@ simulation. @end deffn @geindex command line option; --ieee-asserts= -@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= 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=