diff options
Diffstat (limited to 'doc/using')
| -rw-r--r-- | doc/using/InvokingGHDL.rst | 100 | ||||
| -rw-r--r-- | doc/using/QuickStartGuide.rst | 240 | ||||
| -rw-r--r-- | doc/using/Simulation.rst | 19 |
3 files changed, 186 insertions, 173 deletions
diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index bf7619b7b..ceb25b1a6 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -1,20 +1,22 @@ .. program:: ghdl .. _USING:Invoking: -************* Invoking GHDL -************* +############# The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. There are multiple available commands, but these general rules apply: * The first argument selects the command. The options are used to slightly modify the action. * No option is allowed before the command. Except for the run command, no option is allowed after a filename or a unit name. -.. HINT:: If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line). +.. HINT:: + If the number of options is large and the command line length is beyond the system limit, you can use a response file. An argument that starts with a :samp:`@` is considered as a response file; it is replaced by arguments read from the file (separated by blanks and end of line). -.. HINT:: Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`. +.. HINT:: + Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`. -.. WARNING:: During analysis and elaboration GHDL may read the :samp:`std` and :samp:`ieee` files. The location of these files is based on the prefix, which is (in priority order): +.. WARNING:: + During analysis and elaboration GHDL may read the :samp:`std` and :samp:`ieee` files. The location of these files is based on the prefix, which is (in priority order): * the :option:`--PREFIX` command line option * the :envvar:`GHDL_PREFIX` environment variable @@ -23,14 +25,15 @@ The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. Th You should use the :option:`--disp-config` command to display and debug installation problems. Design building commands -================= +======================== The mostly used commands of GHDL are those to analyze and elaborate a design. + .. index:: cmd analysis Analysis [:samp:`-a`] ----------------- +--------------------- .. option:: -a <[options...] file...> @@ -38,10 +41,11 @@ Analyzes/compiles one or more files, and creates an object file for each source See :ref:`GHDL_options`, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: :samp:`ghdl -a -g my_design.vhdl`. + .. index:: cmd elaboration Elaboration [:samp:`-e`] -------------------- +------------------------ .. option:: -e <[options...] primary_unit [secondary_unit]> @@ -59,10 +63,11 @@ Name of the units must be a simple name, without any dot. You can select the na * If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this con be skipped. + .. index:: cmd run Run [:samp:`-r`] ------------ +---------------- .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]> @@ -79,32 +84,36 @@ This command exists for three reasons: See section ':ref:`USING:Simulation`', for details on options. + .. index:: cmd elaborate and run Elaborate and run [:samp:`--elab-run`] -------------------------- +-------------------------------------- .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]> Acts like the elaboration command (see :option:`-e`) followed by the run command (see :option:`-r`). + .. index:: cmd checking syntax Check syntax [:samp:`-s`] --------------------- +------------------------- .. option:: -s <[options] files> Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update the library. + .. index:: cmd analyze and elaborate Analyze and elaborate [:samp:`-c`] ------------------------------ +---------------------------------- .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]> -.. HINT:: With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode. +.. HINT:: + With GCC/LLVM, :option:`-e` should be used, and :option:`-r` with mcode. The files are first parsed, and then a elaboration is performed, which drives an analysis. Effectively, analysis and elaboration are combined, but there is no explicit call to :option:`-a`. With GCC/LLVM, code is generated during the elaboration. With mcode, the simulation is launched after the elaboration. @@ -117,19 +126,23 @@ The advantages over the traditional approach (analyze and then elaborate) are: * You don't need to know an analysis order. * This command produces smaller executable, since unused units and subprograms do not generate code. -.. HINT:: However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`ieee` libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command. +.. HINT:: + However, you should know that currently most of the time is spent in code generation and the analyze and elaborate command generate code for all units needed, even units of :samp:`std` and :samp:`ieee` libraries. Therefore, according to the design, the time for this command may be higher than the time for the analyze command followed by the elaborate command. + +.. WARNING:: + This command is still under development. In case of problems, you should go back to the traditional way. -.. WARNING:: This command is still under development. In case of problems, you should go back to the traditional way. Design rebuilding commands -=================== +========================== Analyzing and elaborating a design consisting in several files can be tricky, due to dependencies. GHDL has a few commands to rebuild a design. + .. index:: cmd importing files Import [:samp:`-i`] --------------- +------------------- .. option:: -i <[options] file...> @@ -138,22 +151,21 @@ All the files specified in the command line are scanned, parsed and added in the .. HINT:: * Note that all the files are added to the work library. If you have many libraries, you must use the command for each library. - * Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command. See :option:`-m`, to actually build the design. + .. index:: cmd make Make [:samp:`-m`] ------------- +----------------- .. option:: -m <[options] primary [secondary]> Analyze automatically outdated files and elaborate a design. The primary unit denoted by the :samp:`primary` argument must already be known by the system, either because you have already analyzed it (even if you have modified it) or because you have imported it. A file may be outdated because it has been modified (e.g. you just have edited it), or because a design unit contained in the file depends on a unit which is outdated. This rule is of course recursive. * With option :option:`--bind`, 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. - * With option :option:`-f` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. Not outdated units are recompiled. This is useful if you want to compile a design hierarchy with new compilation flags (for example, to add the *-g* debugging option). The make command will only re-analyze design units in the work library. GHDL fails if it has to analyze an outdated unit from another library. @@ -166,17 +178,19 @@ The make command imports files which have been modified. Then, a design hierarch This is not perfect, since the default architecture (the most recently analyzed one) may change while outdated design files are analyzed. In such a case, re-run the make command of GHDL. + .. index:: cmd generate makefile Generate Makefile [:samp:`--gen-makefile`] -------------------------- +------------------------------------------ .. option:: --gen-makefile <[options] primary [secondary]> This command works like the make command (see :option:`-m`), but only a makefile is generated on the standard output. + Options -============ +======= .. index:: IEEE 1164 .. index:: 1164 @@ -306,12 +320,14 @@ Options Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed. + Warnings -============= +======== Some constructions are not erroneous but dubious. Warnings are diagnostic messages that report such constructions. Some warnings are reported only during analysis, others during elaboration. -.. HINT:: You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`. +.. HINT:: + You could disable a warning by using the :samp:`--warn-no-XXX` or :samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`. .. option:: --warn-reserved @@ -371,8 +387,9 @@ Some constructions are not erroneous but dubious. Warnings are diagnostic messag Emit a warning in case of runtime error that is detected during analysis. + Diagnostics Control -======================== +=================== .. option:: -fcolor-diagnostics .. option:: -fno-color-diagnostics @@ -383,7 +400,8 @@ Diagnostics Control .. option:: -fno-diagnostics-show-option Control whether the warning option is displayed at the end of warning messages, so that user can easily know how to disable it. - + + Library commands ================ @@ -396,38 +414,42 @@ A library's source code is usually stored and compiled into its own directory, t Furthermore, GHDL provides a few commands which act on a library: + .. index:: cmd library directory Directory [:samp:`--dir`] ------------------ +------------------------- .. option:: --dir <[options] [libs]> Displays the content of the design libraries (by default the :samp:`work` library). All options are allowed, but only a few are meaningful: :option:`--work`, :option:`--workdir` and :option:`--std`. + .. index:: cmd library clean Clean [:samp:`--clean`] -------------- +----------------------- .. option:: --clean <[options]> Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept. + .. index:: cmd library remove Remove [:samp:`--remove`] --------------- +------------------------- .. option:: --remove <[options]> Do like the clean command but remove the library too. Note that after removing a design library, the files are not known anymore by GHDL. + .. index:: cmd library copy Copy [:samp:`--copy`] ------------- +--------------------- .. option:: --copy <--work=name [options]> @@ -438,16 +460,18 @@ Make a local copy of an existing library. This is very useful if you want to ad ghdl --copy --work=ieee --ieee=synopsys ghdl -a --work=ieee numeric_unsigned.vhd + 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. + .. index:: cmd VPI compile compile [:samp:`--vpi-compile`] -------------------- +------------------------------- .. option:: --vpi-compile <command> @@ -472,7 +496,7 @@ executes:: .. index:: cmd VPI link link [:samp:`--vpi-link`] ----------------- +------------------------- .. option:: --vpi-link <command> @@ -498,7 +522,7 @@ executes:: .. index:: cmd VPI cflags cflags [:samp:`--vpi-cflags`] ------------------- +----------------------------- .. option:: --vpi-cflags @@ -507,7 +531,7 @@ Display flags added by :option:`--vpi-compile`. .. index:: cmd VPI ldflags ldflags [:samp:`--vpi-ldflags`] -------------------- +------------------------------- .. option:: --vpi-ldflags @@ -516,7 +540,7 @@ Display flags added by :option:`--vpi-link`. .. index:: cmd VPI include dir include dir [:samp:`--vpi-include-dir`] ------------------------ +--------------------------------------- .. option:: --vpi-include-dir @@ -525,12 +549,13 @@ Display the include directory added by the compile flags. .. index:: cmd VPI library dir library dir [:samp:`--vpi-library-dir`] ------------------------ +--------------------------------------- .. option:: --vpi-library-dir Display the library directory added by the link flags. + .. _ieee_library_pitfalls: IEEE library pitfalls @@ -651,4 +676,5 @@ It is better to only use the standard packages defined by IEEE, which provides t .. index:: Math_Complex -.. HINT:: The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard. +.. HINT:: + The :samp:`ieee` math packages (:samp:`math_real` and :samp:`math_complex`) provided with `GHDL` are fully compliant with the `IEEE` standard. diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst index 4cbbe8027..f61a86d5d 100644 --- a/doc/using/QuickStartGuide.rst +++ b/doc/using/QuickStartGuide.rst @@ -1,41 +1,40 @@ .. program:: ghdl .. _USING:QuickStart: -****************** Quick Start Guide -****************** +################# In this chapter, you will learn how to use `GHDL` by working on a few examples. The `'Hello world'` program -======================= +=========================== To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` program which saved in a file named :file:`hello.vhdl`: .. code-block:: VHDL - -- Hello world program. - use std.textio.all; -- Imports the standard textio package. + -- Hello world program. + use std.textio.all; -- Imports the standard textio package. - -- Defines a design entity, without any ports. - entity hello_world is - end hello_world; + -- Defines a design entity, without any ports. + entity hello_world is + end hello_world; - architecture behaviour of hello_world is - begin - process - variable l : line; - begin - write (l, String'("Hello world!")); - writeline (output, l); - wait; - end process; - end behaviour; + architecture behaviour of hello_world is + begin + process + variable l : line; + begin + write (l, String'("Hello world!")); + writeline (output, l); + wait; + end process; + end behaviour; .. TIP:: - * Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. - * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in comments. + * Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. + * Unless you use especial characters, either `UTF-8` or `ISO-8859-1` encodings can be used. However, if you do, the latter should be used. The standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. However, GHDL has a relaxing option, :option:`--mb-comments` (multi byte), to allow UTF-8 or other encodings in comments. - First, you have to compile the file; this is called `analysis` of a design file in `VHDL` terms. Run :samp:`ghdl -a hello.vhdl` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library :samp:`work`. - Then, run :samp:`ghdl -e hello_world` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the :samp:`hello_world` entity at the top of the hierarchy. @@ -43,14 +42,15 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p .. code-block:: shell - Hello world! + Hello world! -.. HINT:: If a GCC/LLVM variant of `GHDL` is used: +.. HINT:: + If a GCC/LLVM variant of `GHDL` is used: + + * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created with mcode. + * The elaboration step is compulsory after the analysis and prior to launching the simulation; This wil generate an executable binary named :file:`hello_world`. + * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, :samp:`./hello_world`. See :option:`-r` for more informartion. - * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created with mcode. - * The elaboration step is compulsory after the analysis and prior to launching the simulation; This wil generate an executable binary named :file:`hello_world`. - * As a result, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, :samp:`./hello_world`. See :option:`-r` for more informartion. - .. HINT:: :option:`-e` can be bypassed with mcode, since :option:`-r` actually elaborates the design and saves it on memory before running the simulation. But you can still use it to check for some elaboration problems. The `heartbeat` program @@ -74,9 +74,6 @@ The `heartbeat` program end process; end behaviour; -.. TODO:: Complete `heartbeat` example program - - A full adder ============ @@ -84,87 +81,88 @@ VHDL is generally used for hardware design. This example starts with a `full ad .. code-block:: VHDL - entity adder is - -- `i0`, `i1` and the carry-in `ci` are inputs of the adder. - -- `s` is the sum output, `co` is the carry-out. - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); - end adder; - - architecture rtl of adder is - begin - -- This full-adder architecture contains two concurrent assignment. - -- Compute the sum. - s <= i0 xor i1 xor ci; - -- Compute the carry. - co <= (i0 and i1) or (i0 and ci) or (i1 and ci); - end rtl; + entity adder is + -- `i0`, `i1` and the carry-in `ci` are inputs of the adder. + -- `s` is the sum output, `co` is the carry-out. + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end adder; + + architecture rtl of adder is + begin + -- This full-adder architecture contains two concurrent assignment. + -- Compute the sum. + s <= i0 xor i1 xor ci; + -- Compute the carry. + co <= (i0 and i1) or (i0 and ci) or (i1 and ci); + end rtl; You can analyze this design file, :samp:`ghdl -a adder.vhdl`, and try to execute the `adder` design. But this is useless, since nothing externally visible will happen. In order to check this full adder, a :dfn:`testbench` has to be run. This testbench is very simple, since the adder is also simple: it checks exhaustively all inputs. Note that only the behaviour is tested, timing constraints are not checked. A file named :file:`adder_tb.vhdl` contains the testbench for the adder: .. code-block:: VHDL - -- A testbench has no ports. - entity adder_tb is - end adder_tb; - - architecture behav of adder_tb is - -- Declaration of the component that will be instantiated. - component adder - port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); - end component; - - -- Specifies which entity is bound with the component. - for adder_0: adder use entity work.adder; - signal i0, i1, ci, s, co : bit; - begin - -- Component instantiation. - adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, - s => s, co => co); - - -- This process does the real job. - process - type pattern_type is record - -- The inputs of the adder. - i0, i1, ci : bit; - -- The expected outputs of the adder. - s, co : bit; - end record; - -- The patterns to apply. - type pattern_array is array (natural range <>) of pattern_type; - constant patterns : pattern_array := - (('0', '0', '0', '0', '0'), - ('0', '0', '1', '1', '0'), - ('0', '1', '0', '1', '0'), - ('0', '1', '1', '0', '1'), - ('1', '0', '0', '1', '0'), - ('1', '0', '1', '0', '1'), - ('1', '1', '0', '0', '1'), - ('1', '1', '1', '1', '1')); - begin - -- Check each pattern. - for i in patterns'range loop - -- Set the inputs. - i0 <= patterns(i).i0; - i1 <= patterns(i).i1; - ci <= patterns(i).ci; - -- Wait for the results. - wait for 1 ns; - -- Check the outputs. - assert s = patterns(i).s - report "bad sum value" severity error; - assert co = patterns(i).co - report "bad carry out value" severity error; - end loop; - assert false report "end of test" severity note; - -- Wait forever; this will finish the simulation. - wait; - end process; - end behav; + -- A testbench has no ports. + entity adder_tb is + end adder_tb; + + architecture behav of adder_tb is + -- Declaration of the component that will be instantiated. + component adder + port (i0, i1 : in bit; ci : in bit; s : out bit; co : out bit); + end component; + + -- Specifies which entity is bound with the component. + for adder_0: adder use entity work.adder; + signal i0, i1, ci, s, co : bit; + begin + -- Component instantiation. + adder_0: adder port map (i0 => i0, i1 => i1, ci => ci, + s => s, co => co); + + -- This process does the real job. + process + type pattern_type is record + -- The inputs of the adder. + i0, i1, ci : bit; + -- The expected outputs of the adder. + s, co : bit; + end record; + -- The patterns to apply. + type pattern_array is array (natural range <>) of pattern_type; + constant patterns : pattern_array := + (('0', '0', '0', '0', '0'), + ('0', '0', '1', '1', '0'), + ('0', '1', '0', '1', '0'), + ('0', '1', '1', '0', '1'), + ('1', '0', '0', '1', '0'), + ('1', '0', '1', '0', '1'), + ('1', '1', '0', '0', '1'), + ('1', '1', '1', '1', '1')); + begin + -- Check each pattern. + for i in patterns'range loop + -- Set the inputs. + i0 <= patterns(i).i0; + i1 <= patterns(i).i1; + ci <= patterns(i).ci; + -- Wait for the results. + wait for 1 ns; + -- Check the outputs. + assert s = patterns(i).s + report "bad sum value" severity error; + assert co = patterns(i).co + report "bad carry out value" severity error; + end loop; + assert false report "end of test" severity note; + -- Wait forever; this will finish the simulation. + wait; + end process; + end behav; As usual, you should analyze the design, :samp:`ghdl -a adder_tb.vhdl`. -.. HINT:: Then, if required, elaborate the testbench: :samp:`ghdl -e adder_tb`. You do not need to specify which object files are required, since GHDL knows them and automatically adds them. +.. HINT:: + Then, if required, elaborate the testbench: :samp:`ghdl -e adder_tb`. You do not need to specify which object files are required, since GHDL knows them and automatically adds them. Now, it is time to run the testbench, :samp:`ghdl -r adder_tb`, and check the result on screen:: @@ -187,46 +185,34 @@ Unless you are only studying VHDL, you will work with larger designs than the on .. code-block:: shell - $ cd dlx - $ mkdir work + $ cd dlx + $ mkdir work -- Then, we will run the :samp:`dlx_test_behaviour` design. We need to analyze all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by importing the sources, :samp:`ghdl -i --workdir=work *.vhdl`. +* Then, we will run the :samp:`dlx_test_behaviour` design. We need to analyze all the design units for the design hierarchy, in the correct order. GHDL provides an easy way to do this, by importing the sources, :samp:`ghdl -i --workdir=work *.vhdl`. -- GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, :samp:`ghdl -m --workdir=work dlx_test_behaviour`, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory. +* GHDL knows all the design units of the DLX, but no one have been analyzed. Run the make option, :samp:`ghdl -m --workdir=work dlx_test_behaviour`, which analyzes and elaborates a design. This creates many files in the :file:`work/` directory, and (GCC/LLVM only) the :file:`dlx_test_behaviour` executable in the current directory. .. HINT:: The simulation needs to have a DLX program contained in the file :file:`dlx.out`. This memory image will be loaded in the DLX memory. Just take one sample: :samp:`cp test_loop.out dlx.out`. -- Now, you can run the test suite: :samp:`ghdl -r --workdir=work dlx_test_behaviour`. The test bench monitors the bus and displays each instruction executed. It finishes with an assertion of severity level note: +* Now, you can run the test suite: :samp:`ghdl -r --workdir=work dlx_test_behaviour`. The test bench monitors the bus and displays each instruction executed. It finishes with an assertion of severity level note: .. code-block:: shell - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted -- Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence. This behavior prevents you from running the test bench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: :samp:`ghdl -r --workdir=work dlx_test_behaviour --assert-level=note``. With this option, the program stops just after the previous message: +* Last, since the clock is still running, you have to manually stop the program with the :kbd:`C-c` key sequence. This behavior prevents you from running the test bench in batch mode. However, you may force the simulator to stop when an assertion above or equal a certain severity level occurs. To do so, call run with this option instead: :samp:`ghdl -r --workdir=work dlx_test_behaviour --assert-level=note``. With this option, the program stops just after the previous message: .. code-block:: shell - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed .. TIP:: If you want to make room on your hard drive, you can either: - * Clean the design library with the GHDL command :samp:`ghdl --clean --workdir=work`. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above. - - * Remove the design library with the GHDL command :samp:`ghdl --remove --workdir=work`. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again, and to make the design. - - * Remove the :file:`work/` directory: :samp:`rm -rf work`. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design. + * Clean the design library with the GHDL command :samp:`ghdl --clean --workdir=work`. This removes the executable and all the object files. If you want to rebuild the design at this point, just do the make command as shown above. + * Remove the design library with the GHDL command :samp:`ghdl --remove --workdir=work`. This removes the executable, all the object files and the library file. If you want to rebuild the design, you have to import the sources again, and to make the design. + * Remove the :file:`work/` directory: :samp:`rm -rf work`. Only the executable is kept. If you want to rebuild the design, create the :file:`work/` directory, import the sources, and make the design. .. WARNING:: Sometimes, a design does not fully follow the VHDL standards. For example it uses the badly engineered :samp:`std_logic_unsigned` package. GHDL supports this VHDL dialect through some options: :samp:`--ieee=synopsys -fexplicit`. See section ':ref:`IEEE_library_pitfalls`', for more details. - -Further examples -======================= - -.. TODO:: - - * Add references to examples/tutorials with GHDL. - * Shall `René Doß <https://mail.gna.org/public/ghdl-discuss/2017-01/msg00000.html>` want to contribute adapting his article to RST? - * https://github.com/Obijuan/open-fpga-verilog-tutorial/wiki
\ No newline at end of file diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index 5445bc830..5945588df 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -2,12 +2,12 @@ .. _USING:Simulation: Simulation and runtime -********************** +###################### .. _simulation_options: Simulation options -============ +================== In most system environments, it is possible to pass options while invoking a program. Contrary to most programming languages, there is no @@ -109,7 +109,7 @@ all options available, including the debugging one. .. _export_waves: Export waveforms -============ +================ .. option:: --read-opt-file<=FILENAME> @@ -231,7 +231,7 @@ Export waveforms - `Source code annotation is currently not available for VHDL, however all of GTKWave's other debug features are readily accessible. VHDL support is planned for a future release`. That's something that could be added in the future, but I have no plan for it. Export hierarchy and references -============ +=============================== .. option:: --disp-tree<[=KIND]> @@ -274,20 +274,21 @@ The set of :samp:`file` are analyzed, and then, if the analysis is successful, h Write a report for PSL at the end of simulation. For each PSL cover and assert statements, the name, source location and whether it passed or failed is reported. The file is written using the JSON format, but still being human readable. .. TODO:: - * Maybe worth adding a small example of how to generate a JSON file? + * Maybe worth adding a small example of how to generate a JSON file? .. option:: --file-to-xml Outputs an XML representation of the decorated syntax tree for the input file and its dependencies. It can be used for VHDL tooling using semantic information, like style checkers, documentation extraction, complexity estimation... .. WARNING:: - * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping. - * Note that at this time there is no XML dump of the elaborated design. + * The AST slightly changes from time to time (particularly when new nodes are added for new language features), so be liberal in what is allowed by your tool. Also, the XML can be quite large so consider it only during prototyping. + * Note that at this time there is no XML dump of the elaborated design. + .. index:: debugging Debugging -============ +========= .. option:: --trace-signals @@ -338,7 +339,7 @@ Dump Run Time Information (RTI). Allow :samp:`--work=std` GNU Debugger (GDB) -------------------- +------------------ .. index:: `__ghdl_fatal` |