diff options
Diffstat (limited to 'doc/using')
| -rw-r--r-- | doc/using/CommandReference.rst | 206 | ||||
| -rw-r--r-- | doc/using/ImplementationOfVHDL.rst | 299 | ||||
| -rw-r--r-- | doc/using/ImplementationOfVITAL.rst | 94 | ||||
| -rw-r--r-- | doc/using/InvokingGHDL.rst | 99 | ||||
| -rw-r--r-- | doc/using/QuickStartGuide.rst | 249 | ||||
| -rw-r--r-- | doc/using/Simulation.rst | 120 |
6 files changed, 687 insertions, 380 deletions
diff --git a/doc/using/CommandReference.rst b/doc/using/CommandReference.rst new file mode 100644 index 000000000..d90f9334c --- /dev/null +++ b/doc/using/CommandReference.rst @@ -0,0 +1,206 @@ +.. _REF:Command: + +Command Reference +################# + +.. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. + +Environment variables +===================== + +.. envvar:: GHDL_PREFIX + +Misc commands +============= + +There are a few GHDL commands which are seldom useful. + +.. index:: cmd help + +Help [``-h``] +----------------- + +.. option:: --help, -h + +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 +for that second command are displayed:: + + ghdl --help + ghdl -h + ghdl -h command + +.. index:: cmd display configuration + +Display config [``--disp-config``] +-------------------------------------- + +.. option:: --disp-config <[options]> + +Display the program paths and options used by GHDL. This may be useful to track installation errors. + +.. index:: cmd display standard +.. index:: display ``std.standard`` + +Display standard [``--disp-standard``] +------------------------------------------ + +.. option:: --disp-standard <[options]> + +Display the ``std.standard`` package. + +.. index:: cmd version + +Version [``--version``] +--------------------------- + +.. option:: --version, -v + +Display the GHDL version. + +File commands +============= + +The following commands act on one or several files. These are not analyzed, therefore, they work even if a file has semantic errors. + +.. index:: cmd file pretty printing +.. index:: vhdl to html + +Pretty print [``--pp-html``] +-------------------------------- + +.. option:: --pp-html <[options] file...> + +The files are just scanned and an html file with syntax highlighting is generated on standard output. Since the files +are not even parsed, erroneous files or incomplete designs can be pretty printed. The style of the html file can be +modified with the :option:`--format` option. + +.. index:: cmd file find + +Find [``-f``] +----------------- + +.. option:: -f <file...> + +The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidates to be at the apex of a design hierarchy. + +.. index:: cmd file chop + +Chop [``--chop``] +--------------------- + +.. option:: --chop <files...> + +The provided files are read, and a file is written in the current directory for every design unit. Each filename is built according to the type: + +* For an entity declaration, a package declaration, or a configuration the file name is :file:`NAME.vhdl`, where `NAME` is the name of the design unit. +* For a package body, the filename is :file:`NAME-body.vhdl`. +* Finally, for an architecture `ARCH` of an entity `ENTITY`, the filename is :file:`ENTITY-ARCH.vhdl`. + +Since the input files are parsed, this command aborts in case of syntax error. The command aborts too if a file to be written already exists. + +Comments between design units are stored into the most adequate files. + +This command may be useful to split big files, if your computer doesn't have enough memory to compile such files. The size of the executable is reduced too. + +.. index:: cmd file lines + +Lines [``--lines``] +----------------------- + +.. option:: --lines <files...> + +Display on the standard output lines of files preceded by line number. + +.. _gccllvm-only-programs: + +GCC/LLVM only commands +====================== + +.. index:: cmd GCC/LLVM binding + +Bind [``--bind``] +--------------------- + +.. option:: --bind <[options] primary_unit [secondary_unit]> + +Performs only the first stage of the elaboration command; the list of object files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. + +.. HINT:: + Currently, the objects generated by :option:`--bind` are created in the working directory. This behaviour is different from other object files generated with :option:`-a`, which are always placed in the same directory as the `WORK` library. It is possible to provide an output path with ``ghdl --bind -o path/primary_unit primary_unit``. However, ``ghdl --list-link`` will only search in the current path. + +.. index:: cmd GCC/LLVM linking + +Link [``--link``] +--------------------- + +.. option:: --link <[options] primary_unit [secondary_unit]> + +Performs only the second stage of the elaboration command: the executable is created by linking the files of the object files list. This command is available only for completeness. The elaboration command is equivalent to the bind command followed by the link command. + +.. index:: cmd GCC/LLVM list link + +List link [``--list-link``] +------------------------------- + +.. option:: --list-link <primary_unit [secondary_unit]> + +This command may be used only after a bind command. GHDL displays all the files which will be linked to create an executable and additional arguments for the linker. This command is intended to add object files in a link of a foreign program. This command should be used only after ``ghdl --bind``, as some files generated by it are looked for in the current path. + +.. HINT:: + One of the arguments returned by ``--list-link`` is ``-Wl,--version-script=PREFIX/lib/ghdl/grt.ver``, where `PREFIX` is the installation path of GHDL. This will hide most of the symbols when the target executable binary is built. In some contexts, where the binary is to be loaded dynamically, the user might want additional symbols to be accessible. There are two possible approaches to have it done: + + * Filter the output of ``--list-link`` with e.g. ``sed``. + * Provide an additional non-anonymous version script: ``-Wl,-Wl,--version-script=file.ver``. + +Options +======= + +.. option:: --mb-comments, -C + +Allow multi-bytes chars in a comment. + +.. option:: --syn-binding + +Use synthesizer rules for component binding. During elaboration, if a component is not bound to an entity using VHDL LRM rules, try to find in any known library an entity whose name is the same as the component name. + +This rule is known as the synthesizer rule. + +There are two key points: normal VHDL LRM rules are tried first and entities are searched only in known libraries. A known library is a library which has been named in your design. + +This option is only useful during elaboration. + +.. option:: --GHDL1<=COMMAND> + +Use ``COMMAND`` as the command name for the compiler. If ``COMMAND`` is not a path, then it is searched in the path. + +.. option:: --AS<=COMMAND> + +Use ``COMMAND`` as the command name for the assembler. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``as``. + +.. option:: --LINK<=COMMAND> + +Use ``COMMAND`` as the linker driver. If ``COMMAND`` is not a path, then it is searched in the path. The default is ``gcc``. + +.. _passing-options-to-other-programs: + +Passing options to other programs +================================= + +.. WARNING:: These options are only available with GCC/LLVM. + +For many commands, GHDL acts as a driver: it invokes programs to perform the command. You can pass arbitrary options to these programs. + +Both the compiler and the linker are in fact GCC programs. See the GCC manual for details on GCC options. + +.. option:: -Wc,<OPTION> + +Pass `OPTION` as an option to the compiler. + +.. option:: -Wa,<OPTION> + +Pass `OPTION` as an option to the assembler. + +.. option:: -Wl,<OPTION> + +Pass `OPTION` as an option to the linker. diff --git a/doc/using/ImplementationOfVHDL.rst b/doc/using/ImplementationOfVHDL.rst new file mode 100644 index 000000000..f4ecaf40e --- /dev/null +++ b/doc/using/ImplementationOfVHDL.rst @@ -0,0 +1,299 @@ +.. _REF:ImplVHDL: + +Implementation of VHDL +###################### + +.. _VHDL_standards: + +VHDL standards +============== + +.. index:: VHDL standards + +.. index:: IEEE 1076 + +.. index:: IEEE 1076a + +.. index:: 1076 + +.. index:: 1076a + +.. index:: v87 + +.. index:: v93 + +.. index:: v93c + +.. index:: v00 + +.. index:: v02 + +.. index:: v08 + +Unfortunately, there are many versions of the VHDL +language, and they aren't backward compatible. + +The VHDL language was first standardized in 1987 by IEEE as IEEE 1076-1987, and +is commonly referred as VHDL-87. This is certainly the most important version, +since most of the VHDL tools are still based on this standard. + +Various problems of this first standard have been analyzed by experts groups +to give reasonable ways of interpreting the unclear portions of the standard. + +VHDL was revised in 1993 by IEEE as IEEE 1076-1993. This revision is still +well-known. + +Unfortunately, VHDL-93 is not fully compatible with VHDL-87, i.e. some perfectly +valid VHDL-87 programs are invalid VHDL-93 programs. Here are some of the +reasons: + +* the syntax of file declaration has changed (this is the most visible source + of incompatibility), +* new keywords were introduced (group, impure, inertial, literal, + postponed, pure, reject, rol, ror, shared, sla, sll, sra, srl, + unaffected, xnor), +* some dynamic behaviours have changed (the concatenation is one of them), +* rules have been added. + +Shared variables were replaced by protected types in the 2000 revision of +the VHDL standard. This modification is also known as 1076a. Note that this +standard is not fully backward compatible with VHDL-93, since the type of a +shared variable must now be a protected type (there was no such restriction +before). + +Minor 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 `'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 +:option:`--std=STANDARD <--std>` option, where ``STANDARD`` is one of the list below: + + +87 + Select VHDL-87 standard as defined by IEEE 1076-1987. LRM bugs corrected by + later revisions are taken into account. + +93 + Select VHDL-93; VHDL-87 file declarations are not accepted. + +93c + Select VHDL-93 standard with relaxed rules: + + + * VHDL-87 file declarations are accepted; + + * default binding indication rules of VHDL-02 are used. Default binding rules + are often used, but they are particularly obscure before VHDL-02. + +00 + Select VHDL-2000 standard, which adds protected types. + +02 + Select VHDL-2002 standard. + +08 + Select VHDL-2008 standard (partially implemented). + +Multiple standards can be used in a design: + ++-----+----------------+ +|GROUP| VHDL Standard | ++=====+================+ +| 87 | 87 | ++-----+----------------+ +| 93 | 93, 93c, 00, 02| ++-----+----------------+ +| 08 | 08 | ++-----+----------------+ + +.. note:: + + The standards in each group are considered compatible: you can elaborate a design mixing these standards. However, standards of different groups are not compatible. + +.. _psl_implementation: + +PSL support +=========== + +GHDL implements a subset of :wikipedia:`PSL <Property_Specification_Language>`. + +PSL implementation +------------------ + +A PSL statement is considered a process, so it's not allowed within +a process. + +All PSL assertions must be clocked (GHDL doesn't support unclocked assertion). +Furthermore only one clock per assertion is allowed. + +You can either use a default clock like this: + +.. code-block:: VHDL + + default clock is rising_edge (CLK); + assert always + a -> eventually! b; + +or use a clocked expression (note the use of parentheses): + +.. code-block:: VHDL + + assert (always a -> next[3](b)) @rising_edge(clk); + + +Of course only the simple subset of PSL is allowed. + +Currently the built-in functions are not implemented, see `issue #662 <https://github.com/ghdl/ghdl/issues/662>`_. + +PSL usage +--------- + +PSL annotations embedded in comments +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GHDL understands embedded PSL annotations in VHDL files: + +.. code-block:: VHDL + + -- psl default clock is rising_edge (CLK); + -- psl assert always + -- a -> eventually! b; + end architecture rtl; + +* A PSL assertion statement must appear within a comment that starts + with the `psl` keyword. The keyword must be followed (on the + same line) by a PSL keyword such as `assert` or `default`. + To continue a PSL statement on the next line, just start a new comment. + +.. HINT:: + + As PSL annotations are embedded within comments, you must analyze + your design with option :option:`-fpsl` to enable PSL annotations: + + .. code-block:: bash + + ghdl -a -fpsl vhdl_design.vhdl + ghdl -e vhdl_design + +PSL annotations (VHDL-2008 only) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since VHDL-2008 PSL is integrated in the VHDL language. You can use +PSL in a VHDL(-2008) design without embedding it in comments. + +.. code-block:: VHDL + + default clock is rising_edge (CLK); + assert always + a -> eventually! b; + end architecture rtl; + +.. HINT:: + + You have to use the :option:`--std=08 <--std>` option: + + .. code-block:: bash + + ghdl -a --std=08 vhdl_design.vhdl + ghdl -e --std=08 vhdl_design + +PSL vunit files +^^^^^^^^^^^^^^^ + +GHDL supports vunit (Verification Unit) files. + +.. code-block:: VHDL + + vunit vunit_name (design_name) + { + default clock is rising_edge(clk); + assert always cnt /= 5 abort rst; + } + +* A vunit can contain PSL and VHDL code. + +* It is bound to a VHDL entity or an instance of it. + +* The PSL vunit is in the same scope as the VHDL design it is bound + to. You have access to all objects (ports, types, signals) of the + VHDL design. + +.. HINT:: + + The PSL vunit file has to be analyzed/elaborated together with the VHDL design file, for example: + + .. code-block:: bash + + ghdl -a --std=08 vhdl_design.vhdl vunit.psl + ghdl -e --std=08 vhdl_design + + +Source representation +===================== + +According to the VHDL standard, design units (i.e. entities, +architectures, packages, package bodies, and configurations) may be +independently analyzed. + +Several design units may be grouped into a design file. + +In GHDL, a system file represents a design file. That is, a file compiled by +GHDL may contain one or more design units. + +It is common to have several design units in a design file. + +GHDL does not impose any restriction on the name of a design file +(except that the filename may not contain any control character or +spaces). + +GHDL does not keep a binary representation of the design units analyzed like +other VHDL analyzers. The sources of the design units are re-read when +needed (for example, an entity is re-read when one of its architectures is +analyzed). Therefore, if you delete or modify a source file of a unit +analyzed, GHDL will refuse to use it. + +.. _Library_database: + +Library database +================ + +Each design unit analyzed is placed into a design library. By default, +the name of this design library is ``work``; however, this can be +changed with the :option:`--work` option of GHDL. + +To keep the list of design units in a design library, GHDL creates +library files. The name of these files is :file:`<LIB_NAME>-obj<GROUP>.cf`, where +`<LIB_NAME>` is the name of the library, and `<GROUP>` the VHDL version (87, +93 or 08) used to analyze the design units. + +For details on ``GROUP`` values see section :ref:`VHDL_standards`. + +You don't have to know how to read a library file. You can display it +using the *-d* of `ghdl`. The file contains the name of the +design units, as well as the location and the dependencies. + +The format may change with the next version of GHDL. + +.. _Top_entity: + +Top entity +========== + +There are some restrictions on the entity being at the apex of a design +hierarchy: + +* The generic must have a default value, and the value of a generic is its + default value. +* The ports type must be constrained. + +Using vendor libraries +====================== + +Many vendors libraries have been analyzed with `GHDL`. There are usually no problems. Be sure to use the +:option:`--work` option. However, some problems have been encountered. `GHDL` follows the `VHDL` LRM (the manual which +defines `VHDL`) more strictly than other `VHDL` tools. You could try to relax the restrictions by using the +:option:`--std=93c <--std>`, :option:`-fexplicit`, :option:`-frelaxed-rules` and +:option:`--warn-no-vital-generic <--warn-vital-generic>`. diff --git a/doc/using/ImplementationOfVITAL.rst b/doc/using/ImplementationOfVITAL.rst new file mode 100644 index 000000000..77e7096c0 --- /dev/null +++ b/doc/using/ImplementationOfVITAL.rst @@ -0,0 +1,94 @@ +.. _REF:ImplVITAL: + +**************************** +Implementation of VITAL +**************************** + +.. index:: VITAL + +.. index:: IEEE 1076.4 + +.. index:: 1076.4 + +This chapter describes how VITAL is implemented in GHDL. Support of VITAL is +really in a preliminary stage. Do not expect too much of it as of right now. + +.. _vital_packages: + +VITAL packages +============== + +The VITAL standard or IEEE 1076.4 was first published in 1995, and revised in +2000. + +The version of the VITAL packages depends on the VHDL standard. VITAL +1995 packages are used with the VHDL 1987 standard, while VITAL 2000 +packages are used with other standards. This choice is based on the +requirements of VITAL: VITAL 1995 requires the models follow the VHDL +1987 standard, while VITAL 2000 requires the models follow VHDL 1993. + +The VITAL 2000 packages were slightly modified so that they conform to +the VHDL 1993 standard (a few functions are made pure and a few +impure). + +.. _vhdl_restrictions_for_vital: + +VHDL restrictions for VITAL +=========================== + +The VITAL standard (partially) implemented is the IEEE 1076.4 standard +published in 1995. + +This standard defines restriction of the VHDL language usage on VITAL +model. A :dfn:`VITAL model` is a design unit (entity or architecture) +decorated by the `VITAL_Level0` or `VITAL_Level1` attribute. +These attributes are defined in the `ieee.VITAL_Timing` package. + +Currently, only VITAL level 0 checks are implemented. VITAL level 1 models +can be analyzed, but GHDL doesn't check they comply with the VITAL standard. + +Moreover, GHDL doesn't check (yet) that timing generics are not read inside +a VITAL level 0 model prior the VITAL annotation. + +The analysis of a non-conformant VITAL model fails. You can disable the +checks of VITAL restrictions with the *--no-vital-checks*. Even when +restrictions are not checked, SDF annotation can be performed. + +.. _backannotation: + +Backannotation +============== + +.. index:: SDF + +:dfn:`Backannotation` is the process of setting VITAL generics with timing +information provided by an external files. + +The external files must be SDF (Standard Delay Format) files. GHDL +supports a tiny subset of SDF version 2.1. Other version numbers can be +used, provided no features added by later versions are used. + +Hierarchical instance names are not supported. However you can use a list of +instances. If there is no instance, the top entity will be annotated and +the celltype must be the name of the top entity. If there is at least one +instance, the last instance name must be a component instantiation label, and +the celltype must be the name of the component declaration instantiated. + +Instances being annotated are not required to be VITAL compliant. However +generics being annotated must follow rules of VITAL (e.g., type must be a +suitable vital delay type). + +Currently, only timing constraints applying on a timing generic of type +`VitalDelayType01` has been implemented. This SDF annotator is +just a proof of concept. Features will be added with the following GHDL +release. + +Negative constraint calculation +=============================== + +Negative constraint delay adjustments are necessary to handle negative +constraints such as a negative setup time. This step is defined in the VITAL +standard and should occur after backannotation. + +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. diff --git a/doc/using/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index 94e58866a..bd7d98022 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -1,4 +1,3 @@ -.. program:: ghdl .. _USING:Invoking: Invoking GHDL @@ -32,14 +31,19 @@ The most commonly used commands of GHDL are those to analyze and elaborate a des .. index:: cmd analysis +.. _Analysis:command: + Analysis [``-a``] ---------------------- +----------------- .. option:: -a <[options...] file...> -Analyzes/compiles one or more files, and creates an object file for each source file. Any argument starting with a dash is an option, the others are filenames. No options are allowed after a filename argument. GHDL analyzes each filename in the given order, and stops the analysis in case of error (remaining files are not analyzed). +Analyzes/compiles one or more files, and creates an object file for each source file. Any argument starting with a +dash is an option, the others are filenames. No options are allowed after a filename argument. GHDL analyzes each +filename in the given order, and stops the analysis in case of error (remaining files are not analyzed). -See :ref:`GHDL:options`, for details on the GHDL options. For example, to produce debugging information such as line numbers, use: ``ghdl -a -g my_design.vhdl``. +See :ref:`GHDL:options`, for details on the GHDL options. For example, to produce debugging information such as line +numbers, use: ``ghdl -a -g my_design.vhdl``. .. index:: cmd elaboration @@ -47,11 +51,13 @@ See :ref:`GHDL:options`, for details on the GHDL options. For example, to produc .. _Elaboration:command: Elaboration [``-e``] ------------------------- +-------------------- .. option:: -e <[options...] primary_unit [secondary_unit]> -Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default configurations and the default binding indications according to the LRM rules. It also generates the list of object files required for the executable. Then, it links all these files with the runtime library. +Re-analyzes all the configurations, entities, architectures and package declarations, and creates the default +configurations and the default binding indications according to the LRM rules. It also generates the list of object +files required for the executable. Then, it links all these files with the runtime library. * The elaboration command, :option:`-e`, must be followed by a name of either: @@ -59,11 +65,18 @@ Re-analyzes all the configurations, entities, architectures and package declarat * an entity unit * an entity unit followed by a name of an architecture unit -Name of the units must be a simple name, without any dot. You can select the name of the `WORK` library with the :option:`--work=NAME` option, as described in :ref:`GHDL:options`. See section :ref:`Top_entity`, for the restrictions on the root design of a hierarchy. + Name of the units must be a simple name, without any dot. You can select the name of the `WORK` library with the + :option:`--work=NAME <--work>` option, as described in :ref:`GHDL:options`. See section :ref:`Top_entity`, for the + restrictions on the root design of a hierarchy. -* If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable containing the code of the VHDL sources, the elaboration code and simulation code to execute a design hierarchy. The executable is created in the current directory and the the filename is the name of the primary unit, or for the latter case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). Option :option:`-o` followed by a filename can override the default executable filename. +* If the GCC/LLVM backend was enabled during the compilation of GHDL, the elaboration command creates an executable + containing the code of the VHDL sources, the elaboration code and simulation code to execute a design hierarchy. The + executable is created in the current directory and the the filename is the name of the primary unit, or for the latter + case, the concatenation of the name of the primary unit, a dash, and the name of the secondary unit (or architecture). + Option ``-o`` followed by a filename can override the default executable filename. -* If mcode is used, this command elaborates the design but does not generate anything. Since the run command also elaborates the design, this can be skipped. +* If mcode is used, this command elaborates the design but does not generate anything. Since the run command also + elaborates the design, this can be skipped. .. WARNING:: This elaboration command is not a complete elaboration in terms of the VHDL standard. The actual elaboration is performed at runtime. Therefore, in order to get a complete VHDL elaboration without running the simulation, ``ghdl --elab-run --no-run`` is required. @@ -71,12 +84,14 @@ Name of the units must be a simple name, without any dot. You can select the nam .. index:: cmd run +.. _Run:command: + Run [``-r``] ----------------- +------------ .. option:: -r <[options...] primary_unit [secondary_unit] [simulation_options...]> -Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration_command>`. +Runs/simulates a design. The options and arguments are the same as for the :ref:`elaboration command <Elaboration:command>`. * GGC/LLVM: simply, the filename of the executable is determined and it is executed. Options are ignored. You may also directly execute the program. The executable must be in the current directory. * mcode: the design is elaborated and the simulation is launched. As a consequence, you must use the same options used during analysis. @@ -93,7 +108,7 @@ See section :ref:`USING:Simulation`, for details on options. .. index:: cmd elaborate and run Elaborate and run [``--elab-run``] --------------------------------------- +---------------------------------- .. option:: --elab-run <[elab_options...] primary_unit [secondary_unit] [run_options...]> @@ -103,7 +118,7 @@ Acts like the elaboration command (see :option:`-e`) followed by the run command .. index:: cmd checking syntax Check syntax [``-s``] -------------------------- +--------------------- .. option:: -s <[options] files> @@ -113,7 +128,7 @@ Analyze files but do not generate code. This command may be used to check the sy .. index:: cmd analyze and elaborate Analyze and elaborate [``-c``] ----------------------------------- +------------------------------ .. option:: -c <[options] file... -<e|r> primary_unit [secondary_unit]> @@ -146,8 +161,10 @@ Analyzing and elaborating a design consisting of several files can be tricky, du .. index:: cmd importing files +.. _Import:command: + Import [``-i``] -------------------- +--------------- .. option:: -i <[options] file...> @@ -163,15 +180,17 @@ See :option:`-m`, to actually build the design. .. index:: cmd make +.. _Make:command: + Make [``-m``] ------------------ +------------- .. option:: -m <[options] primary [secondary]> Analyze automatically outdated files and elaborate a design. The primary unit denoted by the ``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 have just 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. 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). +* With 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 ``-f`` (force), GHDL analyzes all the units of the work library needed to create the design hierarchy. 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. @@ -215,8 +234,6 @@ Options .. index:: IEEE 1076.3 .. index:: 1076.3 -.. HINT:: Besides the options described below, `GHDL` passes any debugging options (those that begin with :option:`-g`) and optimizations options (those that begin with :option:`-O` or :option:`-f`) to `GCC`. Refer to the `GCC` manual for details. - .. index:: WORK library .. option:: --work=<LIB_NAME> @@ -231,7 +248,7 @@ Options Specify the directory where the ``WORK`` library is located. When this option is not present, the ``WORK`` library is in the current directory. The object files created by the compiler are always placed in the same directory as the ``WORK`` library. - Use option :option:`-P` to specify where libraries other than ``WORK`` are placed. + Use option :option:`-P <-P<DIRECTORY>>` to specify where libraries other than ``WORK`` are placed. .. option:: --std=<STANDARD> @@ -321,6 +338,14 @@ Options Enable parsing of PSL assertions within comments. See section :ref:`PSL_implementation` for more details. +.. option:: --format=<FORMAT> + + Define the output format of some options, such as :option:`--pp-html` or :option:`--xref-html`. + + * By default or when :option:`--format=html2 <--format>` is specified, generated files follow the HTML 2.0 standard, and colours are specified with `<FONT>` tags. However, colours are hard-coded. + + * If :option:`--format=css <--format>` is specified, generated files follow the HTML 4.0 standard, and use the CSS-1 file :file:`ghdl.css` to specify colours. This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user to change colours or appearance. Refer to a generated file and its comments for more information. + .. option:: --no-vital-checks .. option:: --vital-checks @@ -330,7 +355,7 @@ Options Currently, VITAL checks are only partially implemented. See section :ref:`VHDL_restrictions_for_VITAL` for more details. -.. option:: --PREFIX<=PATH> +.. option:: --PREFIX=<PATH> Use :file:`PATH` as the prefix path to find commands and pre-installed (``std`` and ``ieee``) libraries. @@ -461,9 +486,9 @@ Library commands .. _Create_a_Library: .. index:: create your own library -A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhd``. +A new library is created implicitly, by compiling entities (packages etc.) into it: ``ghdl -a --work=my_custom_lib my_file.vhdl``. -A library's source code is usually stored and compiled into its own directory, that you specify with the :option:`--workdir` option: ``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd``. See also the :option:`-P` command line option. +A library's source code is usually stored and compiled into its own directory, that you specify with the :option:`--workdir` option: ``ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhdl``. See also the :option:`-P <-P<DIRECTORY>>` command line option. Furthermore, GHDL provides a few commands which act on a library: @@ -471,7 +496,7 @@ Furthermore, GHDL provides a few commands which act on a library: .. index:: cmd library directory Directory [``--dir``] -------------------------- +--------------------- .. option:: --dir <[options] [libs]> @@ -480,8 +505,10 @@ Displays the content of the design libraries (by default the ``work`` library). .. index:: cmd library clean +.. _Clean:command: + Clean [``--clean``] ------------------------ +------------------- .. option:: --clean <[options]> @@ -490,8 +517,10 @@ Try to remove any object, executable or temporary file it could have created. So .. index:: cmd library remove +.. _Remove:command: + Remove [``--remove``] -------------------------- +--------------------- .. option:: --remove <[options]> @@ -502,7 +531,7 @@ known anymore by GHDL. .. index:: cmd library copy Copy [``--copy``] ---------------------- +----------------- .. option:: --copy <--work=name [options]> @@ -525,7 +554,7 @@ command before its execution. .. index:: cmd VPI compile compile [``--vpi-compile``] -------------------------------- +--------------------------- .. option:: --vpi-compile <command> @@ -550,7 +579,7 @@ executes:: .. index:: cmd VPI link link [``--vpi-link``] -------------------------- +--------------------- .. option:: --vpi-link <command> @@ -576,7 +605,7 @@ executes:: .. index:: cmd VPI cflags cflags [``--vpi-cflags``] ------------------------------ +------------------------- .. option:: --vpi-cflags @@ -585,7 +614,7 @@ Display flags added by :option:`--vpi-compile`. .. index:: cmd VPI ldflags ldflags [``--vpi-ldflags``] -------------------------------- +--------------------------- .. option:: --vpi-ldflags @@ -594,7 +623,7 @@ Display flags added by :option:`--vpi-link`. .. index:: cmd VPI include dir include dir [``--vpi-include-dir``] ---------------------------------------- +----------------------------------- .. option:: --vpi-include-dir @@ -603,7 +632,7 @@ Display the include directory added by the compile flags. .. index:: cmd VPI library dir library dir [``--vpi-library-dir``] ---------------------------------------- +----------------------------------- .. option:: --vpi-library-dir @@ -615,7 +644,7 @@ Display the library directory added by the link flags. IEEE library pitfalls ===================== -When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, the ``ieee`` library contains non standard packages such as ``std_logic_arith``. These packages are not standard because there are not described by an IEEE standard, even if they have been put in the `IEEE` library. Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor and those of Synopsys. Furthermore, since they are not well thought out, their use has pitfalls. For example, this description has an error during compilation: +When you use options :option:`--ieee=synopsys <--ieee>` or :option:`--ieee=mentor <--ieee>`, the ``ieee`` library contains non standard packages such as ``std_logic_arith``. These packages are not standard because there are not described by an IEEE standard, even if they have been put in the `IEEE` library. Furthermore, they are not really de-facto standard, because there are slight differences between the packages of Mentor and those of Synopsys. Furthermore, since they are not well thought out, their use has pitfalls. For example, this description has an error during compilation: .. code-block:: VHDL diff --git a/doc/using/QuickStartGuide.rst b/doc/using/QuickStartGuide.rst deleted file mode 100644 index 572d7853b..000000000 --- a/doc/using/QuickStartGuide.rst +++ /dev/null @@ -1,249 +0,0 @@ -.. 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 general purpose of `VHDL`, here is a commented `'Hello world'` program which is saved in a file named :file:`hello.vhdl`: - -.. code-block:: VHDL - - -- 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; - - 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 ``.vhdl`` and ``.vhd`` extensions are used for VHDL source files, while ``.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 ``ghdl -a hello.vhdl`` in the `shell`. This command creates or updates a file :file:`work-obj93.cf`, which describes the library ``work``. -- Then, run ``ghdl -e hello_world`` in the `shell`. Option :option:`-e` means :dfn:`elaborate`, which is used to build a design, with the ``hello_world`` entity at the top of the hierarchy. -- Last, you can directly launch the simulation running ``ghdl -r hello_world`` in the `shell`. The result of the simulation will be shown on screen: - -.. code-block:: shell - - Hello world! - -.. 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 mandatory after running the analysis and prior to launching the simulation. This will 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, ``./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 -======================= - -.. code-block:: VHDL - - library ieee; - use ieee.std_logic_1164.all; - - entity heartbeat is - port ( clk: out std_logic); - end heartbeat; - - architecture behaviour of heartbeat - is - constant clk_period : time := 10 ns; - begin - -- Clock process definition - clk_process: process - begin - clk <= '0'; - wait for clk_period/2; - clk <= '1'; - wait for clk_period/2; - end process; - end behaviour; - -A full adder -============ - -VHDL is generally used for hardware design. This example starts with a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_ described in a file named :file:`adder.vhdl`: - -.. 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 assignments. - -- 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, ``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; - - -As usual, you should analyze the design, ``ghdl -a adder_tb.vhdl``. - -.. HINT:: - Then, if required, elaborate the testbench: ``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, ``ghdl -r adder_tb``, and check the result on screen:: - - adder_tb.vhdl:52:7:(assertion note): end of test - -If your design is rather complex, you'd like to inspect signals. Signal values can be dumped using multiple formats (see section :ref:`export_waves` for more information). The resulting file can be read with a wave viewer such as `GtkWave <http://gtkwave.sourceforge.net/>`_. - -As explained in the `manual <http://gtkwave.sourceforge.net/gtkwave.pdf>`_, GtkWave *'relies on a post-mortem approach through the use of dumpfiles'*. Therefore, you should first simulate your design and dump a waveform file, say VCD: ``ghdl -r adder_tb --vcd=adder.vcd``. Then, you can view the dump: ``gtkwave adder.vcd``. - -See section :ref:`simulation_options`, for more details on other runtime options. - -Starting with a design -====================== - -Unless you are only studying VHDL, you will work with larger designs than the ones of the previous examples. Let's see how to analyze and run a bigger design, such as the DLX model suite written by Peter Ashenden which is distributed under the terms of the GNU General Public License. A copy is kept on `ghdl.free.fr/dlx.tar.gz <http://ghdl.free.fr/dlx.tar.gz>`_ . - -- First, untar the sources: ``tar zxvf dlx.tar.gz``. - -.. HINT:: In order not to pollute the sources with the library, it is a good idea to create a :file:`work/` subdirectory for the `WORK` library. To any GHDL commands, we will add the :option:`--workdir=work` option, so that all files generated by the compiler (except the executable) will be placed in this directory. - - .. code-block:: shell - - $ cd dlx - $ mkdir work - -* Then, we will run the ``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, ``ghdl -i --workdir=work *.vhdl``. - -* GHDL knows all the design units of the DLX, but none of them has been analyzed. Run the make option, ``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: ``cp test_loop.out dlx.out``. - -* Now, you can run the test suite: ``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 - -* Lastly, 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: ``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 - -.. TIP:: If you want to make room on your hard drive, you can either: - - * Clean the design library with the GHDL command ``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 ``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 make the design. - * Remove the :file:`work/` directory: ``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 might use the badly engineered ``std_logic_unsigned`` package. GHDL supports this VHDL dialect through some options: ``--ieee=synopsys -fexplicit``. See section :ref:`IEEE_library_pitfalls`, for more details. - - -Starting with your design -========================= - -Usually your design is more complex than the previous ones. The main -tips are: - -* Don't forget to select the VHDL standard you want to use. The - default is ``--std=93c`` which means VHDL-93 with some relaxed - rules. Use ``--std=08`` for VHDL-2008 (albeit not fully - implemented). All the units must be analyzed with the same standard. - -* Use ``--work=LIB_NAME`` to analyze files into the ``LIB_NAME`` library. - If you analyze other files from a different directory, give the path - of the ``LIB_NAME`` library using ``-P/path/to/name/directory/``. - -* Use ``--ieee=synopsys`` if your design depends on the non-standard - ieee library. - -* Use ``-fexplicit`` if needed. - -* Use the same options for elaboration. - -So, to analyze a file: ``ghdl -a --std=08 --work=mylib myfile.vhdl`` -To elaborate and run: ``ghdl --elab-run --std=08 top``. diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index 012a15621..0718fe079 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -1,4 +1,3 @@ -.. program:: ghdl .. _USING:Simulation: Simulation and runtime @@ -23,9 +22,7 @@ The exit status of the simulation is ``EXIT_SUCCESS`` (0) if the simulation completes, or ``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 :option:`--help` option lists -all options available, including the debugging ones. +Here is the list of the most useful options. For further info, see :ref:`DEV:Debugging`. .. option:: -gGENERIC=VALUE @@ -35,7 +32,7 @@ all options available, including the debugging ones. This is currently a run option; but in the future it will be deprecated to become an elaboration option only. -.. option:: --assert-level<=LEVEL> +.. option:: --assert-level=<LEVEL> Select the assertion level at which an assertion violation stops the simulation. `LEVEL` is the name from the `severity_level` @@ -50,10 +47,10 @@ all options available, including the debugging ones. stop simulation, but the assertion violation at the ``note`` severity level would only display a message. - Option :option:`--assert-level=none` prevents any assertion violation from stopping + Option :option:`--assert-level=none <--assert-level>` prevents any assertion violation from stopping simulation. -.. option:: --ieee-asserts<=POLICY> +.. option:: --ieee-asserts=<POLICY> Select how the assertions from ``ieee`` units are handled. `POLICY` can be ``enable`` (the default), @@ -63,7 +60,7 @@ all options available, including the debugging ones. This option can be useful to avoid assertion messages from ``ieee.numeric_std`` (and other ``ieee`` packages). -.. option:: --stop-time<=TIME> +.. option:: --stop-time=<TIME> Stop the simulation after ``TIME``. ``TIME`` is expressed as a time value, *without* any space. The time is the simulation time, not @@ -74,7 +71,7 @@ all options available, including the debugging ones. $ ./my_design --stop-time=10ns $ ./my_design --stop-time=ps -.. option:: --stop-delta<=N> +.. option:: --stop-delta=<N> Stop the simulation after `N` delta cycles in the same current time. The default is 5000. @@ -89,12 +86,12 @@ all options available, including the debugging ones. Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO). -.. option:: --max-stack-alloc<=N> +.. option:: --max-stack-alloc=<N> Emit an error message in case of allocation on the stack of an object larger than `N` KB. Use 0 to disable these checks. -.. option:: --sdf<=PATH=FILENAME> +.. option:: --sdf=<PATH=FILENAME> Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`. @@ -115,11 +112,11 @@ all options available, including the debugging ones. See section :ref:`Backannotation`, for more details. -.. option:: --vpi<=FILENAME> +.. option:: --vpi=<FILENAME> Load VPI module. -.. option:: --vpi-trace<=FILE> +.. option:: --vpi-trace=<FILE> Trace vpi calls to FILE. @@ -171,9 +168,9 @@ Export waveforms the design. Otherwise throws an error, because it won't erase an existing file. -.. option:: --vcd<=FILENAME> +.. option:: --vcd=<FILENAME> -.. option:: --vcdgz<=FILENAME> +.. option:: --vcdgz=<FILENAME> .. index:: vcd @@ -186,7 +183,7 @@ Export waveforms then the standard output is used, otherwise a file is created or overwritten. - The :option:`--vcdgz` option is the same as the *--vcd* option, + The :option:`--vcdgz` option is the same as the :option:`--vcd` option, but the output is compressed using the `zlib` (`gzip` compression). However, you can't use the ``-`` filename. Furthermore, only one VCD file can be written. @@ -224,13 +221,13 @@ Export waveforms Do not write date in the VCD file. -.. option:: --fst<=FILENAME> +.. option:: --fst=<FILENAME> Write the waveforms into an `fst` file that can be displayed by `gtkwave`. The `fst` files are much smaller than VCD or `GHW` files, but it handles only the same signals as the VCD format. -.. option:: --wave<=FILENAME> +.. option:: --wave=<FILENAME> Write the waveforms into a `ghw` (GHdl Waveform) file. Currently, all the signals are dumped into the waveform file, you cannot select a hierarchy @@ -244,7 +241,7 @@ Export waveforms Export hierarchy and references =============================== -.. option:: --disp-tree<[=KIND]> +.. option:: --disp-tree=<KIND> .. index:: display design hierarchy @@ -266,17 +263,17 @@ Export hierarchy and references Stop the simulation before the first cycle. This may be used with :option:`--disp-tree` to display the tree without simulating the whole design. This option actually elaborates the design, so it will catch any bound error in port maps. -.. option:: --xref-html <[options] file...> +.. option:: --xref-html [options] files... - To easily navigate through your sources, you may generate cross-references. This command generates an html file for each ``file`` given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. An index of the files is created too. + To easily navigate through your sources, you may generate cross-references. This command generates an html file for + each ``file`` given in the command line, with syntax highlighting and full cross-reference: every identifier is a + link to its declaration. An index of the files is created too. - The set of ``file`` are analyzed, and then, if the analysis is successful, html files are generated in the directory specified by the :option:`-o <dir>` option, or :file:`html/` directory by default. + The set of ``files`` are analyzed, and then, if the analysis is successful, html files are generated in the directory + specified by the ``-o <DIR>`` option, or :file:`html/` directory by default. The style of the html file can be + modified with the :option:`--format` option. - * If the option :option:`--format=html2` is specified, then the generated html files follow the HTML 2.0 standard, and colours are specified with `<FONT>` tags. However, colours are hard-coded. - - * If the option :option:`--format=css` is specified, then the generated html files follow the HTML 4.0 standard, and use the CSS-1 file :file:`ghdl.css` to specify colours. This file is generated only if it does not already exist (it is never overwritten) and can be customized by the user to change colours or appearance. Refer to a generated file and its comments for more information. - -.. option:: --psl-report<=FILENAME> +.. option:: --psl-report=<FILENAME> 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 is still human readable. @@ -287,72 +284,3 @@ Export hierarchy and references .. 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. - - -.. index:: debugging - -Debugging -========= - -.. option:: --trace-signals - - Display signals after each cycle. - -.. option:: --trace-processes - - Display process name before each cycle. - -.. option:: --stats - - Display run-time statistics. - -.. option:: --disp-order - - Display signals order. - -.. option:: --disp-sources - - Display sources while displaying signals. - -.. option:: --disp-sig-types - - Display signal types. - -.. option:: --disp-signals-map - - Display map bw declared signals and internal signals. - -.. option:: --disp-signals-table - - Display internal signals. - -.. option:: --checks - - Do internal checks after each process run. - -.. option:: --activity<=LEVEL> - - Watch activity of LEVEL signals: LEVEL is ``all``, ``min`` (default) or ``none`` (unsafe). - -.. option:: --dump-rti - - Dump Run Time Information (RTI). - -.. option:: --bootstrap - - Allow ``--work=std`` - -GNU Debugger (GDB) ------------------- - -.. index:: `__ghdl_fatal` - -.. WARNING:: Debugging VHDL programs using `GDB` is possible only with GCC/LLVM. - -GDB is a general purpose debugger for programs compiled by GCC. Currently, there is no VHDL support for GDB. It may be difficult to inspect variables or signals in GDB. However, it is still able to display the stack frame in case of error or to set a breakpoint at a specified line. - -GDB can be useful to catch a runtime error, such as indexing an array beyond its bounds. All error check subprograms call the ``__ghdl_fatal`` procedure. Therefore, to a catch runtime error, set a breakpoint like this:: - - (gdb) break __ghdl_fatal - -When the breakpoint is hit, use the ``where`` or ``bt`` command to display the stack frames. |