diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/_static/theme_overrides.css | 8 | ||||
| -rw-r--r-- | doc/about.rst (renamed from doc/About.rst) | 0 | ||||
| -rw-r--r-- | doc/changelog/Roadmap.rst | 33 | ||||
| -rw-r--r-- | doc/contribute.rst (renamed from doc/Contributing.rst) | 0 | ||||
| -rw-r--r-- | doc/getting/Building.rst | 39 | ||||
| -rw-r--r-- | doc/getting/VendorPrimitives.md | 16 | ||||
| -rw-r--r-- | doc/licenses.rst (renamed from doc/Licenses.rst) | 2 | ||||
| -rw-r--r-- | doc/references/CommandReference.rst | 212 | ||||
| -rw-r--r-- | doc/using/InvokingGHDL.rst | 831 | ||||
| -rw-r--r-- | doc/using/QuickStartGuide.rst | 201 | ||||
| -rw-r--r-- | doc/using/Simulation.rst | 108 |
11 files changed, 556 insertions, 894 deletions
diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index a1a61eae9..7f808783b 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -1,6 +1,6 @@ /* Change font sizes*/ html,body{font-size:98%;} -p{font-size:95%} +p{font-size:95%;margin-bottom:12px} .wy-breadcrumbs li.wy-breadcrumbs-aside{font-size:95%} .rst-versions{font-size:50%} .rst-versions .rst-current-version {font-size: 165%} @@ -62,4 +62,8 @@ div.wy-menu.rst-pro{display: none !important;max-width: 260px} /* Set text justification in paragraphs and list items to fully justified [borrowed from PoC-Library]*/ .section p {text-align:justify;} -.simple li {text-align:justify;}
\ No newline at end of file +.simple li {text-align:justify;} + +/*Reduce margin below lists*/ +.rst-content .section ul, .rst-content .toctree-wrapper ul, article ul {margin-bottom: 12px} +.rst-content blockquote {margin-bottom: 12px;}
\ No newline at end of file diff --git a/doc/About.rst b/doc/about.rst index 9b11ed5bf..9b11ed5bf 100644 --- a/doc/About.rst +++ b/doc/about.rst diff --git a/doc/changelog/Roadmap.rst b/doc/changelog/Roadmap.rst index d5b3be9fb..5dfba58b1 100644 --- a/doc/changelog/Roadmap.rst +++ b/doc/changelog/Roadmap.rst @@ -13,9 +13,36 @@ I have several axes for `GHDL` improvements: * Style checks * VITAL acceleration -.. TODO:: +TODOs +================= - - Convert VendorPrimitives Markdown to RST - - SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so? +- RTD builds fail if EPUB is activated. +- Convert VendorPrimitives Markdown to RST +- SVG images are not shown in the PDF. That's because LaTeX is used. Can any package be added to allow so? + +Options shown in the command line help, but not found in the doc: + +* :samp:`--expect-failure invert exit status` +* :samp:`--has-feature=X test presence of feature X` +* :samp:`--list-features display the list of features` +* :samp:`--vpi=FILENAME load VPI module` +* :samp:`--vpi-trace[=FILE] trace vpi calls to FILE` +* :samp:`--dump-rti dump Run Time Information` +* :samp:`--trace-signals disp signals after each cycle` +* :samp:`--trace-processes disp process name before each cycle` +* :samp:`--stats display run-time statistics` +* :samp:`--disp-order disp signals order` +* :samp:`--disp-sources disp sources while displaying signals` +* :samp:`--disp-sig-types disp signal types` +* :samp:`--disp-signals-map disp map bw declared sigs and internal sigs` +* :samp:`--disp-signals-table disp internal signals` +* :samp:`--checks do internal checks after each process run` +* :samp:`--activity=LEVEL watch activity of LEVEL signals: LEVEL is all, min (default) or none (unsafe)` +* :samp:`-C --mb-comments allow multi-bytes chars in a comment` + + * https://github.com/tgingold/ghdl/issues/132 + +* :samp:`--bootstrap allow --work=std` +* :samp:`--syn-binding use synthesis default binding rule` .. todolist::
\ No newline at end of file diff --git a/doc/Contributing.rst b/doc/contribute.rst index 36a3c0f38..36a3c0f38 100644 --- a/doc/Contributing.rst +++ b/doc/contribute.rst diff --git a/doc/getting/Building.rst b/doc/getting/Building.rst index 68f086c56..9c357b476 100644 --- a/doc/getting/Building.rst +++ b/doc/getting/Building.rst @@ -20,11 +20,11 @@ GHDL currently supports three supported different backends (code generators): `m | | - Easier to build than GCC | | +------------------------+------------------------------------------------------------------------------------------+---------------------------------------------------------+ -.. HINT:: The output of both GCC and LLVM is an executable file, but `mcode` does not generate any. Therefore, if using GCC/LLVM, the call with argument :samp:`-r` can be replaced with direct execution of the binary. +.. HINT:: The output of both GCC and LLVM is an executable file, but `mcode` does not generate any. Therefore, if using GCC/LLVM, the call with argument :samp:`-r` can be replaced with direct execution of the binary. See section :ref:`USING:QuickStart`. After making your choice, you can jump to the corresponding section below. However, we suggest you to read :ref:`BUILD:dir_structure` before, so that you know where the content is placed and which temporal files are expected to be created. -.. HINT:: Since GHDL is written in `Ada`, independently of the code generator you use, the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for :samp:`x86` (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_ . Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`. +.. HINT:: Since GHDL is written in `Ada`, independently of the code generator you use, the `GNU Ada compiler`, `GNAT GPL`, is required, 2014 (or later) for :samp:`x86` (32 or 64 bits). `GNAT GPL` can be downloaded anonymously from `libre.adacore.com <http://libre.adacore.com/tools/gnat-gpl-edition/>`_. Then, untar and run the doinstall script. Alternatively, most GNU/Linux provide a package named :samp:`gcc-ada` or :samp:`gcc-gnat`. .. TODO:: @@ -37,9 +37,41 @@ After making your choice, you can jump to the corresponding section below. Howev Directory structure ================= +* :samp:`src`: sources of GHDL, all of them in Ada. + +* :samp:`libraries`: mostly third party libraries such as, `ieee`, `mentor`, `std`, `synopsys` and `vital`. Except a few shell and `Python` scripts, all the content is written in VHDL. + + * Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with GHDL, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. These are located in :samp:`libraries/vendor`. See `Vendor Primitives <VendorPrimitives.html>`_ for information on how to use them. + +* :samp:`dist`: scripts and auxiliar files to build GHDL in different environments: + + * :samp:`gcc`: header and configuration files to build GHDL with GCC (all the platforms). + + * :samp:`linux`: build and test script written in shell, and other auxiliar files used to i) launch docker containers and ii) automate multiple builds in `Travis CI <https://travis-ci.org/>`_. + + * :samp:`windows`: + + * :samp:`mcode`: + + * :samp:`appveyor`: + +* :samp:`doc`: `Markdown` and `reStructuredText` sources and auxiliar files to build the documentation with `Sphinx <http://www.sphinx-doc.org>`_. Indeed, `Read the docs <http://readthedocs.org>`_ (RTD) is used to automatically build and deploy this site and/or PDF you are reading. + +* :samp:`testsuite`: see section :ref:`test_suites`. + +* `.yml` configuration files for CI environments (:samp:`readthedocs`, :samp:`travis` and :samp:`appveyor`) and `ignore` files for source control management tools (:samp:`git` and :samp:`.hg`). + +* Files for building GHDL: :samp:`configure` and :samp:`Makefile.in`. + +* Auxiliar files for development: :samp:`.gdbinit` and :samp:`ghdl.gpr.in` (GNAT project file). + +* Text files: :samp:`COPYING.md`, :samp:`NEWS.md` and :samp:`README.md`. + .. TODO:: - Directory structure of the main branch [1138: #279] + - [@1138-4EB|@Paebbels] Replace link to VendorPrimitives, when the file is translated from md to rst. + + - [@Paebbels] Add brief description of how the content in dist/windows is ordered. Mcode backend ================= @@ -157,6 +189,7 @@ Windows? Install file for the binary distribution of GHDL. The binary are installed in /usr/local directory. You cannot change this default location, unless you set links. You must be root to install this distribution. To install ghdl: `tar -C / -jxvf @TARFILE@.tar.bz2`. Note: you must also have a C compiler and zlib installed. +.. _test_suites: Test suites ================= diff --git a/doc/getting/VendorPrimitives.md b/doc/getting/VendorPrimitives.md index 3b9c9b11f..b25b4bb9a 100644 --- a/doc/getting/VendorPrimitives.md +++ b/doc/getting/VendorPrimitives.md @@ -1,16 +1,12 @@ ## Vendor Primitives -Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with *GHDL*, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. There are also popular simulation and verification libraries like [OSVVM][osvvm] and [VUnit][vunit], which can be pre-compiled, too. +Vendors like Altera, Lattice and Xilinx have their own simulation libraries, especially for FPGA primitives, soft and hard macros. These libraries can not be shipped with *GHDL*, but we offer prepared compile scripts to pre-compile the vendor libraries, if the vendor tool is present on the computer. There are also popular simulation and verification libraries like [OSVVM](http://osvvm.org) and [VUnit](https://github.com/LarsAsplund/vunit), which can be pre-compiled, too. -The compilation scripts are writen in the shell languages: *PowerShell* for *Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize the *GHDL* warning and error lines with the help of `grc/grcat` ([generic colourizer][grc]). - -- [osvvm]: http://osvvm.org/ -- [vunit]: https://github.com/LarsAsplund/vunit -- [grc]: http://kassiopeia.juls.savba.sk/~garabik/software/grc.html +The compilation scripts are writen in the shell languages: *PowerShell* for *Windows* |trade| and *Bash* for *GNU/Linux*. The compile scripts can colorize the *GHDL* warning and error lines with the help of `grc/grcat` ([generic colourizer](http://kassiopeia.juls.savba.sk/~garabik/software/grc.html)). ##### Supported Vendors Libraries - - Altera/Intel Quartus (≥13.0): + - Altera/Intel Quartus (13.0 or later): - `lpm`, `sgate` - `altera`, `altera_mf`, `altera_lnsim` - `arriaii`, `arriaii_pcie_hip`, `arriaiigz` @@ -21,19 +17,19 @@ The compilation scripts are writen in the shell languages: *PowerShell* for *Win - `stratixiv`, `stratixiv_pcie_hip` - `stratixv`, `stratixv_pcie_hip` - `fiftyfivenm`, `twentynm` - - Lattice (≥3.6): + - Lattice (3.6 or later): - `ec` - `ecp`, `ecp2`, `ecp3`, `ecp5u` - `lptm`, `lptm2` - `machxo`, `machxo2`, `machxo3l` - `sc`, `scm` - `xp`, `xp2` - - Xilinx ISE (≥14.0): + - Xilinx ISE (14.0 or later): - `unisim` (incl. `secureip`) - `unimacro` - `simprim` (incl. `secureip`) - `xilinxcorelib` - - Xilinx Vivado (≥2014.1): + - Xilinx Vivado (2014.1 or later): - `unisim` (incl. `secureip`) - `unimacro` diff --git a/doc/Licenses.rst b/doc/licenses.rst index a7e70d0c3..078d43199 100644 --- a/doc/Licenses.rst +++ b/doc/licenses.rst @@ -65,7 +65,7 @@ Jensen, Adam FreeBSD builds Koch, Markus vendor pre-compile script for Lattice (GNU/Linux) Koontz, David Mac OSX builds, LRM compliance work, bugfix analyses Lehmann, Patrick Windows compile scripts, vendor library pre-compile scripts (win+lin), building in MinGW, AppVeyor integration. -Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix STD theme +Martinez-Corral, Unai Docker builds, Travis-CI & Docker, adapt/fix RTD theme van Rantwijk, Joris Debian packaging ========================= ============================================================ diff --git a/doc/references/CommandReference.rst b/doc/references/CommandReference.rst index ed7869dba..771d2386e 100644 --- a/doc/references/CommandReference.rst +++ b/doc/references/CommandReference.rst @@ -3,4 +3,216 @@ Command Reference ################# +.. HINT:: The most common commands and options are shown in section :ref:`USING:Invoking`. Here the advanced and experimental features are described. +Misc commands +============= + +There are a few GHDL commands which are seldom useful. + +.. _Help_command: + +Help [:samp:`-h`] +------------ + +.. index:: -h command + +.. index:: --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 +for this later command are displayed:: + + ghdl --help + ghdl -h + ghdl -h command + + +.. _Disp_config_command: + +Display config [:samp:`--disp-config`] +------------------- + +.. index:: --disp-config command + +.. index:: display configuration + +:samp:`ghdl --disp-config [options]` + +Display the program paths and options used by GHDL. This may be useful to track installation errors. + +Display standard [:samp:`--disp-standard`] +--------------------- + +.. index:: --disp-standard command + +.. index:: display :samp:`std.standard` + +:samp:`ghdl --disp-standard [options]` + +Display the :samp:`std.standard` package. + +Version [:samp:`--version`] +--------------- + +.. index:: --version command + +.. index:: version + +:samp:`ghdl --version` + +Display the `GHDL` version and exit. + +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. + +Pretty print [:samp:`--pp-html`] +-------------------- + +.. index:: --pp-html command + +.. index:: pretty printing + +.. index:: vhdl to html + +:samp:`ghdl --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: + +* By default or when the :option:`--format=html2` option is specified, the output is an HTML 2.0 file, with colours set through `<FONT>` tags. +* When the :option:`--format=css` option is specified, the output is an HTML 4.0 file, with colours set through a CSS file, whose name is :file:`ghdl.css`. See :ref:`Cross-reference_command`, for more details about this CSS file. + +Find [:samp:`-f`] +------------ + +.. index:: -f command + +:samp:`ghdl -f file...` + +The files are scanned, parsed and the names of design units are displayed. Design units marked with two stars are candidate to be at the apex of a design hierarchy. + +Chop [:samp:`--chop`] +------------ + +.. index:: --chop command + +:samp:`ghdl --chop files` + +The provided files are read, and a file is written in the current directory for every design unit. Each filename is build 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 has not enough memory to compile such files. The size of the executable is reduced too. + +Lines [:samp:`--lines`] +------------- + +.. index:: --lines command + +:samp:`ghdl --lines files` + +Display on the standard output lines of files preceded by line number. + +GCC/LLVM only commands +================= + +.. _Bind_command: + +Bind [:samp:`--bind`] +------------ + +.. index:: binding + +.. index:: --bind command + +:samp:`ghdl --bind [options] primary_unit [secondary_unit]` + +Performs only the first stage of the elaboration command; the list of objects files is created but the executable is not built. This command should be used only when the main entry point is not GHDL. + +.. _Link_command: + +Link [:samp:`--link`] +------------ + +.. index:: linking + +.. index:: --link command + +:samp:`ghdl --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. + +.. _List_link_command: + +List link [:samp:`--list-link`] +----------------- + +.. index:: --list-link command + +:samp:`ghdl --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. This command is intended to add object files in a link of a foreign program. + +GHDL options +================= + +.. 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 synthesizer rule. + + There are two key points: normal VHDL LRM rules are tried first and + entities are searched only in known library. A known library is a + library which has been named in your design. + + This option is only useful during elaboration. + +.. option:: --GHDL1=<COMMAND> + + Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is + not a path, then it is searched in the path. + +.. option:: --AS=<COMMAND> + + Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is + not a path, then it is searched in the path. The default is :samp:`as`. + +.. option:: --LINK=<COMMAND> + + Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is + not a path, then it is searched in the path. The default is :samp:`gcc`. + +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/InvokingGHDL.rst b/doc/using/InvokingGHDL.rst index bf901bccc..73c821b92 100644 --- a/doc/using/InvokingGHDL.rst +++ b/doc/using/InvokingGHDL.rst @@ -5,276 +5,208 @@ Invoking GHDL ************* -The form of the :program:`ghdl` command is:: +The form of the :program:`ghdl` command is :samp:`ghdl command [options...]`. There are multiple available commands, but these general rules apply: - ghdl command [options...] +* 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. -The GHDL program has several commands. The first argument selects -the command. The options are used to slightly modify the action. +.. 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). -No option is allowed before the command. Except for the run command, -no option is allowed after a filename or a unit name. +.. HINT:: Only the most common commands and options are shown here. For most advanced and experimental features see section :ref:`REF:Command`. -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). +.. WARNING:: During analysis and elaboration GHDL may read the `std` and `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 + * a built-in default path. It is a hard-coded path on GNU/Linux and the value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows. + + You should use the :option:`--disp-config` command (:ref:`--disp-config <Disp_config_command>` for details) to disp and debug installation problems. Design building commands ================= The mostly used commands of GHDL are those to analyze and elaborate a design. -Analysis command +Analysis [:samp:`-a`] ---------------- .. index:: analysis .. index:: -a command -Analyze one or several files:: - - ghdl -a [options...] file... - -The analysis command compiles one or more files, and creates an -object file for each source file. The analysis command is selected with -:option:`-a` switch. 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 (the following 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:: +:samp:`ghdl -a [options...] file...` - ghdl -a -g my_design.vhdl +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: :samp:`ghdl -a -g my_design.vhdl`. .. _Elaboration_command: -Elaboration command +Elaboration [:samp:`-e`] ------------------- .. index:: elaboration .. index:: -e command -Elaborate a design:: - - ghdl -e [options..] primary_unit [secondary_unit] - - -On GNU/Linux, if the GCC 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. -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 :option:`-e` switch, and must be -followed by either: +:samp:`ghdl -e [options..] primary_unit [secondary_unit]` -* a name of a configuration unit -* a name of an entity unit -* a name of an entity unit followed by a name of an architecture 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 objects files required for the executable. Then, it links all these files with the runtime library. The actual elaboration is performed at runtime. -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`. +* The elaboration command, :option:`-e`, must be followed by a name of either: -See :ref:`Top_entity`, for the restrictions on the root design of a -hierarchy. + * a configuration unit + * 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 :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 later 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. -On GNU/Linux the filename of the executable is the name of the -primary unit, or for the later case, the concatenation of the name of -the primary unit, a dash, and the name of the secondary unit (or -architecture). On Windows there is no executable generated. - -The :option:`-o` followed by a filename can override the default -executable filename. - -For the elaboration command, `GHDL` 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 objects files -required for the executable. Then, it links all these files with the -runtime library. - -The actual elaboration is performed at runtime. - -On Windows this command can be skipped because it is also done by the -run command. +* 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. .. _Run_command: -Run command +Run [:samp:`-r`] ----------- .. index:: run .. index:: -r command -Run (or simulate) a design:: - - ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...] +:samp:`ghdl -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>`. -The options and arguments are the same as for the elaboration command, :ref:`Elaboration_command`. - -On GNU/Linux this command simply determines the filename of the executable -and executes it. Options are ignored. You may also directly execute -the program. The executable must be in the current directory. +* 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. This command exists for three reasons: -* You don't have to create the executable program name. +* You are using GCC/LLVM, but you don't need to create the executable program name. * It is coherent with the :option:`-a` and :option:`-e` commands. -* It works with the Windows implementation, where the code is generated in - memory. - -On Windows this command elaborates and launches the simulation. As a consequence -you must use the same options used during analysis. +* It works with mcode implementation, where the executable code is generated in memory. See :ref:`Simulation_and_runtime`, for details on options. -Elaborate and run command +Elaborate and run [:samp:`--elab-run`] ------------------------- .. index:: elaborate and run .. index:: --elab-run command -Elaborate and then simulate a design unit:: - - ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...] - +:samp:`ghdl --elab-run [elab_options...] primary_unit [secondary_unit] [run_options...]` -This command acts like the elaboration command (see :ref:`Elaboration_command`) -followed by the run command (see :ref:`Run_command`). +Acts like the elaboration command (see :ref:`elaboration command <Elaboration_command>`) followed by the run command (see :ref:`run command <Run_command>`). -.. _Bind_command: - -Bind command ------------- - -.. index:: binding +.. _Check_syntax_command: -.. index:: --bind command +Check syntax [:samp:`-s`] +-------------------- -Bind a design unit and prepare the link step:: +.. index:: checking syntax - ghdl --bind [options] primary_unit [secondary_unit] +.. index:: -s command +:samp:`ghdl -s [options] files` -This command is only available on GNU/Linux. +Analyze files but do not generate code. This command may be used to check the syntax of files. It does not update +the library. -This performs only the first stage of the elaboration command; the list -of objects files is created but the executable is not built. This -command should be used only when the main entry point is not ghdl. +.. _Analyze_and_elaborate_command: -.. _Link_command: +Analyze and elaborate [:samp:`-c`] +----------------------------- -Link command ------------- +.. index:: Analyze and elaborate command -.. index:: linking +.. index:: -c command -.. index:: --link command +GCC/LLVM: :samp:`ghdl -c [options] file... -e primary_unit [secondary_unit]` -Link an already bound design unit:: +mcode: :samp:`ghdl -c [options] file... -r primary_unit [secondary_unit]` - ghdl --link [options] primary_unit [secondary_unit] +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. -This 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. +All the units of the files are put into the `work` library. But, the work library is neither read from disk nor saved. Therefore, you must give all the files of the `work` library your design needs. -.. _List_link_command: +The advantages over the traditional approach (analyze and then elaborate) are: -List link command ------------------ +* The compilation cycle is achieved in one command. +* Since the files are only parsed once, the compilation cycle may be faster. +* You don't need to know an analysis order. +* This command produces smaller executable, since unused units and subprograms do not generate code. -.. index:: --list-link 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. -Display files which will be linked:: +.. WARNING:: This command is still under development. In case of problems, you should go back to the traditional way. - ghdl --list-link primary_unit [secondary_unit] +Design rebuilding commands +=================== -This command is only available on GNU/Linux. +Analyzing and elaborating a design consisting in several files can be tricky, +due to dependencies. GHDL has a few commands to rebuild a design. -This command may be used only after a bind command. GHDL displays all -the files which will be linked to create an executable. This command is -intended to add object files in a link of a foreign program. +Import [:samp:`-i`] +-------------- -.. _Check_syntax_command: +.. index:: importing files -Check syntax command --------------------- +.. index:: -i command -.. index:: checking syntax +:samp:`ghdl -i [options] file...` -.. index:: -s command +All the files specified in the command line are scanned, parsed and added in the libraries but as not yet analyzed. No object files are created. It's purpose is to localize design units in the design files. The make command will then be able to recursively build a hierarchy from an entity name or a configuration name. -Analyze files but do not generate code:: +.. HINT:: - ghdl -s [options] files + * Note that all the files are added to the work library. If you have many libraries, you must use the command for each library. -This command may be used to check the syntax of files. It does not update -the library. + * Since the files are parsed, there must be correct files. However, since they are not analyzed, many errors are tolerated by this command. -.. _Analyze_and_elaborate_command: +See see :ref:`-m <Make_command>`, to actually build the design. -Analyze and elaborate command ------------------------------ +.. _Make_command: -.. index:: Analyze and elaborate command +Make [:samp:`-m`] +------------ -.. index:: -c command +.. index:: make -Analyze files and elaborate them at the same time. +.. index:: -m command -On GNU/Linux:: +:samp:`ghdl -m [options] primary [secondary]` - ghdl -c [options] file... -e primary_unit [secondary_unit] +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:`-b` (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. -On Windows:: +* 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). - ghdl -c [options] file... -r primary_unit [secondary_unit] +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. +The purpose of this command is to be able to compile a design without prior knowledge of file order. In the VHDL model, some units must be analyzed before others (e.g. an entity before its architecture). It might be a nightmare to analyze a full design of several files, if you don't have the ordered list of file. This command computes an analysis order. -This command combines analysis and elaboration: files are analyzed and -the unit is then elaborated. However, code is only generated during the -elaboration. On Windows the simulation is launched. +The make command fails when a unit was not previously parsed. For example, if you split a file containing several design units into several files, you must either import these new files or analyze them so that GHDL knows in which file these units are. -To be more precise, the files are first parsed, and then the elaboration -drives the analysis. Therefore, there is no analysis order, and you don't -need to care about it. +The make command imports files which have been modified. Then, a design hierarchy is internally built as if no units are outdated. Then, all outdated design units, using the dependencies of the design hierarchy, are analyzed. +If necessary, the design hierarchy is elaborated. -All the units of the files are put into the `work` library. But, the -work library is neither read from disk nor saved. Therefore, you must give -all the files of the `work` library your design needs. +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. -The advantages over the traditional approach (analyze and then elaborate) are: +Generate Makefile [:samp:`--gen-makefile`] +------------------------- -* The compilation cycle is achieved in one command. -* Since the files are only parsed once, the compilation cycle may be faster. -* You don't need to know an analysis order -* This command produces smaller executable, since unused units and subprograms - do not generate code. +.. index:: --gen-makefile command -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. +:samp:`ghdl --gen-makefile [options] primary [secondary]` -This command is still experimental. In case of problems, you should go back -to the traditional way. +This command works like the make command (see :ref:`-m <Make_command>`), but only a makefile is generated on the standard output. .. _GHDL_Options: -GHDL options +Options ============ .. index:: IEEE 1164 @@ -285,16 +217,11 @@ GHDL options .. index:: 1076.3 -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. - +.. 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=<NAME> - - .. index:: WORK library +.. option:: --work=<NAME> Specify the name of the :samp:`WORK` library. Analyzed units are always placed in the library logically named :samp:`WORK`. With this option, @@ -308,7 +235,6 @@ manual for details. `VHDL` rules forbid you to add units to the :samp:`std` library. Furthermore, you should not put units in the :samp:`ieee` library. - .. option:: --workdir=<DIR> Specify the directory where the :samp:`WORK` library is located. When this @@ -319,14 +245,12 @@ manual for details. Use option :option:`-P` to specify where libraries other than :samp:`WORK` are placed. - .. option:: --std=<STD> Specify the standard to use. By default, the standard is :samp:`93c`, which means VHDL-93 accepting VHDL-87 syntax. For details on :samp:`STD` values see :ref:`VHDL_standards`. - .. option:: --ieee=<VER> .. index:: ieee library @@ -367,7 +291,6 @@ manual for details. To avoid errors, you must use the same `IEEE` library for all units of your design, and during elaboration. - .. option:: -P<DIRECTORY> Add `DIRECTORY` to the end of the list of directories to be searched for @@ -379,18 +302,13 @@ manual for details. :option:`--workdir=` option, or in the current directory if the latter option is not specified. - .. option:: -fexplicit When two operators are overloaded, give preference to the explicit declaration. This may be used to avoid the most common pitfall of the :samp:`std_logic_arith` package. See :ref:`IEEE_library_pitfalls`, for an example. - This option is not set by default. I don't think this option is a - good feature, because it breaks the encapsulation rule. When set, an - operator can be silently overridden in another package. You'd better to fix - your design and use the :samp:`numeric_std` package. - +.. WARNING:: This option is not set by default. I don't think this option is a good feature, because it breaks the encapsulation rule. When set, an operator can be silently overridden in another package. You'd better fix your design and use the :samp:`numeric_std` package. .. option:: -frelaxed-rules @@ -420,13 +338,11 @@ manual for details. This option also relaxes the rules about pure functions. Violations result in warnings instead of errors. - .. option:: -fpsl Enable parsing of PSL assertions within comments. See :ref:`PSL_implementation`, for more details. - .. option:: --no-vital-checks .. option:: --vital-checks @@ -440,112 +356,27 @@ manual for details. Currently, VITAL checks are only partially implemented. See :ref:`VHDL_restrictions_for_VITAL`, for more details. - -.. 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 synthesizer rule. - - There are two key points: normal VHDL LRM rules are tried first and - entities are searched only in known library. A known library is a - library which has been named in your design. - - This option is only useful during elaboration. - - .. option:: --PREFIX=<PATH> Use :file:`PATH` as the prefix path to find commands and pre-installed (std and ieee) libraries. - -.. option:: --GHDL1=<COMMAND> - - Use :samp:`COMMAND` as the command name for the compiler. If :samp:`COMMAND` is - not a path, then it is searched in the path. - - -.. option:: --AS=<COMMAND> - - Use :samp:`COMMAND` as the command name for the assembler. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`as`. - - -.. option:: --LINK=<COMMAND> - - Use :samp:`COMMAND` as the linker driver. If :samp:`COMMAND` is - not a path, then it is searched in the path. The default is :samp:`gcc`. - - .. option:: -v Be verbose. For example, for analysis, elaboration and make commands, GHDL displays the commands executed. - -Passing options to other programs -================================= - -These options are only available on GNU/Linux. - -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. - -GHDL Diagnostics Control -======================== - -.. option:: -fcolor-diagnostics -.. option:: -fno-color-diagnostics - - Control whether diagnostic messages are displayed in color. The - default is on when the standard output is a terminal. - -.. option:: -fdiagnostics-show-option -.. 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. - - -GHDL warnings +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. - -You could disable a warning by using the :samp:`--warn-no-XXX` or -:samp:`-Wno-XX` instead of :samp:`--warn-XXX` or :samp:`-WXXX`. +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`. .. option:: --warn-reserved Emit a warning if an identifier is a reserved word in a later VHDL standard. - .. option:: --warn-default-binding During analyze, warns if a component instantiation has neither @@ -554,7 +385,6 @@ You could disable a warning by using the :samp:`--warn-no-XXX` or configuration. :ref:`VHDL_standards`, for more details about default binding rules. - .. option:: --warn-binding During elaboration, warns if a component instantiation is not bound @@ -569,7 +399,6 @@ You could disable a warning by using the :samp:`--warn-no-XXX` or generate statement to select a component according to the implementation, you will certainly get warnings. - .. option:: --warn-library Warns if a design unit replaces another design unit with the same name. @@ -580,7 +409,6 @@ You could disable a warning by using the :samp:`--warn-no-XXX` or Warns if a generic name of a vital entity is not a vital generic name. This is set by default. - .. option:: --warn-delayed-checks Warns for checks that cannot be done during analysis time and are @@ -592,153 +420,64 @@ You could disable a warning by using the :samp:`--warn-no-XXX` or These are checks for no wait statement in a procedure called in a sensitized process and checks for pure rules of a function. - .. option:: --warn-body Emit a warning if a package body which is not required is analyzed. If a package does not declare a subprogram or a deferred constant, the package does not require a body. - .. option:: --warn-specs Emit a warning if an all or others specification does not apply. - .. option:: --warn-unused Emit a warning when a subprogram is never used. - .. option:: --warn-error When this option is set, warnings are considered as errors. - .. option:: --warn-nested-comment Emit a warning if a :samp:`/*` appears within a block comment (vhdl 2008). - .. option:: --warn-parenthesis Emit a warning in case of weird use of parenthesis - .. option:: --warn-runtime-error Emit a warning in case of runtime error that is detected during analysis. +Diagnostics Control +======================== -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. - -Import command --------------- - -.. index:: importing files - -.. index:: -i command - -Add files in the work design library:: - - ghdl -i [options] file... - - -All the files specified in the command line are scanned, parsed and added in -the libraries but as not yet analyzed. No object files are created. - -The purpose of this command is to localize design units in the design files. -The make command will then be able to recursively build a hierarchy from -an entity name or a configuration name. - -Since the files are parsed, there must be correct files. However, since they -are not analyzed, many errors are tolerated by this command. - -Note that all the files are added to the work library. If you have many -libraries, you must use the command for each library. - -See :ref:`Make_command`, to actually build the design. - -.. _Make_command: - -Make command ------------- - -.. index:: make - -.. index:: -m command - - -Analyze automatically outdated files and elaborate a design:: - - ghdl -m [options] primary [secondary] - - -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. GHDL analyzes -all outdated files. 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 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. - -With the :option:`-f` (force) option, 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. - -The purpose of this command is to be able to compile a design without prior -knowledge of file order. In the VHDL model, some units must be analyzed -before others (e.g. an entity before its architecture). It might be a -nightmare to analyze a full design of several files, if you don't have -the ordered list of file. This command computes an analysis order. - -The make command fails when a unit was not previously parsed. For -example, if you split a file containing several design units into -several files, you must either import these new files or analyze them so -that GHDL knows in which file these units are. - -The make command imports files which have been modified. Then, a design -hierarchy is internally built as if no units are outdated. Then, all outdated -design units, using the dependencies of the design hierarchy, are analyzed. -If necessary, the design hierarchy is elaborated. - -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. +.. option:: -fcolor-diagnostics +.. option:: -fno-color-diagnostics -Generate Makefile command -------------------------- + Control whether diagnostic messages are displayed in color. The default is on when the standard output is a terminal. -.. index:: --gen-makefile command +.. option:: -fdiagnostics-show-option +.. option:: -fno-diagnostics-show-option -Generate a Makefile to build a design unit:: + 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 +================ - ghdl --gen-makefile [options] primary [secondary] +.. _Create_a_Library: +.. index:: create your own library -This command works like the make command (see :ref:`Make_command`), but only a -makefile is generated on the standard output. +A new library is created implicitly, by compiling entities (packages etc.) into it: :samp:`ghdl -a --work=my_custom_lib my_file.vhd`. -Library commands -================ +A library's source code is usually stored and compiled into its own directory, that you specify with the :option:`--workdir` option: :samp:`ghdl -a --work=my_custom_lib --workdir=my_custom_libdir my_custom_lib_srcdir/my_file.vhd`. See also the :option:`-P<DIRECTORY>` command line option. -GHDL has a few commands which act on a library. +Furthermore, GHDL provides a few commands which act on a library: -Directory command +Directory [:samp:`--dir`] ----------------- .. index:: displaying library @@ -746,285 +485,79 @@ Directory command .. index:: --dir command .. option::--dir -Display the name of the units contained in a design library:: +:samp:`ghdl --dir [options] [libs]` - ghdl --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=NAME`, :option:`--workdir=PATH` and :option:`--std=VER`. -The directory command, selected with the `--dir` command line argument -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=NAME`, -:option:`--workdir=PATH` and :option:`--std=VER`. - -Clean command +Clean [:samp:`--clean`] ------------- .. index:: cleaning .. index:: --clean command -Remove object and executable files but keep the library:: - - ghdl --clean [options] +:samp:`ghdl --clean [options]` - -GHDL tries to remove any object, executable or temporary file it could -have created. Source files are not removed. - -There is no short command line form for this option to prevent accidental -clean up. +Try to remove any object, executable or temporary file it could have created. Source files are not removed. The library is kept. .. _Remove_command: -Remove command +Remove [:samp:`--remove`] -------------- .. index:: cleaning all .. index:: --remove command -Do like the clean command but remove the library too:: - - ghdl --remove [options] +:samp:`ghdl --remove [options]` - -There is no short command line form for this option to prevent accidental -clean up. Note that after removing a design library, the files are not +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. .. _Copy_command: -Copy command +Copy [:samp:`--copy`] ------------ .. index:: copying library .. index:: --copy command -Make a local copy of an existing library:: - - ghdl --copy --work=name [options] +:samp:`ghdl --copy --work=name [options]` - -Make a local copy of an existing library. This is very useful if you want to -add unit to the :samp:`ieee` library: +Make a local copy of an existing library. This is very useful if you want to add unit to the :samp:`ieee` library: .. code-block:: shell ghdl --copy --work=ieee --ieee=synopsys ghdl -a --work=ieee numeric_unsigned.vhd - -.. _Create_a_Library: - -Create a Library ----------------- - -.. index:: create your own library - -A new library is created by compiling entities (packages etc.) into it:: - - ghdl -a --work=my_custom_lib my_file.vhd - - -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:`-PPATH` command line option. - .. _Cross-reference_command: -Cross-reference command +Cross-reference [:samp:`--xref-html`] ======================= To easily navigate through your sources, you may generate cross-references:: - ghdl --xref-html [options] file... - - -This command generates an html file for each :samp:`file` given in the command -line, with syntax highlighting and full cross-reference: every identifier is -a link to its declaration. Besides, an index of the files is created too. - -The set of :samp:`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. - -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. - -File commands -============= - -The following commands act on one or several files. They do not analyze -files, therefore, they work even if a file has semantic errors. - -Pretty print command --------------------- - -.. index:: --pp-html command - -.. index:: pretty printing - -.. index:: vhdl to html - -Generate HTML on standard output from VHDL:: - - ghdl --pp-html [options] file... +:samp:`ghdl --xref-html [options] file...` +This command generates an html file for each :samp:`file` given in the command line, with syntax highlighting and full cross-reference: every identifier is a link to its declaration. Besides, an index of the files is created too. -The files are just scanned and an html file, with syntax highlighting is -generated on standard output. +The set of :samp:`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. -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. -By default or when the :option:`--format=html2` option is specified, the output -is an HTML 2.0 file, with colours set through `<FONT>` tags. When the -:option:`--format=css` option is specified, the output is an HTML 4.0 file, -with colours set through a CSS file, whose name is :file:`ghdl.css`. -See :ref:`Cross-reference_command`, for more details about this CSS file. - -Find command ------------- - -.. index:: -f command - -Display the name of the design units in files:: - - ghdl -f file... - - -The files are scanned, parsed and the names of design units are displayed. -Design units marked with two stars are candidate to be at the apex of a -design hierarchy. - -Chop command ------------- - -.. index:: --chop command - -Chop (or split) files at design unit:: - - ghdl --chop files - - -`GHDL` reads files, and writes a file in the current directory for -every design unit. - -The filename of a design unit is build according to the unit. 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 has not -enough memory to compile such files. The size of the executable is -reduced too. - -Lines command -------------- - -.. index:: --lines command - -Display on the standard output lines of files preceded by line number:: - - ghdl --lines files - - -Misc commands -============= - -There are a few GHDL commands which are seldom useful. - -.. _Help_command: - -Help command ------------- - -.. index:: -h command - -.. index:: --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 -for this later command are displayed:: - - ghdl --help - ghdl -h - ghdl -h command - - -.. _Disp_config_command: - -Disp config command -------------------- - -.. index:: --disp-config command - -.. index:: display configuration - -Display the program paths and options used by GHDL:: - - ghdl --disp-config [options] - - -This may be useful to track installation errors. - -Disp standard command ---------------------- - -.. index:: --disp-standard command - -.. index:: display :samp:`std.standard` - -Display the :samp:`std.standard` package:: - - ghdl --disp-standard [options] - - -Version command ---------------- - -.. index:: --version command - -.. index:: version - -Display the `GHDL` version and exit:: - - ghdl --version +* 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. 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 +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 +compile [:samp:`--vpi-compile`] ------------------- .. index:: --vpi-compile command @@ -1047,7 +580,7 @@ executes:: .. _VPI_link_command: -VPI link command +link [:samp:`--vpi-link`] ---------------- .. index:: --vpi-link command @@ -1071,83 +604,54 @@ executes:: .. _VPI_cflags_command: -VPI cflags command +cflags [:samp:`--vpi-cflags`] ------------------ .. index:: --vpi-cflags command -Display flags added by :option:`--vpi-compile`:: - - ghdl --vpi-cflags +:samp:`ghdl --vpi-cflags` +Display flags added by :option:`--vpi-compile`. .. _VPI_ldflags_command: -VPI ldflags command +ldflags [:samp:`--vpi-ldflags`] ------------------- .. index:: --vpi-ldflags command -Display flags added by :option:`--vpi-link`:: +:samp:`ghdl --vpi-ldflags` - ghdl --vpi-ldflags +Display flags added by :option:`--vpi-link`. .. _VPI_include_dir_command: -VPI include dir command +include dir [:samp:`--vpi-include-dir`] ----------------------- .. index:: --vpi-include-dir command -Display the include directory added by the compile flags:: +:samp:`ghdl --vpi-include-dir` - ghdl --vpi-include-dir +Display the include directory added by the compile flags. .. _VPI_library_dir_command: -VPI library dir command +library dir [:samp:`--vpi-library-dir`] ----------------------- .. index:: --vpi-library-dir command -Display the library directory added by the link flags:: - - ghdl --vpi-library-dir - - -Installation Directory -====================== - -During analysis and elaboration `GHDL` may read the `std` -and `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 +:samp:`ghdl --vpi-library-dir` -* - a built-in default path. It is a hard-coded path on GNU/Linux and the - value of the :samp:`HKLM\Software\Ghdl\Install_Dir` registry entry on Windows. - -You should use the :option:`--disp-config` command (:ref:`Disp_config_command` for details) to disp and debug installation problems. +Display the library directory added by the link flags. .. _ieee_library_pitfalls: IEEE library pitfalls ===================== -When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, -the `IEEE` library contains non standard packages such as -:samp:`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, their use has pitfalls. For -example, this description has error during compilation: +When you use options :option:`--ieee=synopsys` or :option:`--ieee=mentor`, the :samp:`ieee` library contains non standard packages such as :samp:`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, their use has pitfalls. For example, this description has error during compilation: .. code-block:: VHDL @@ -1199,21 +703,12 @@ have been split for readability): [std_logic_vector, std_logic_vector return boolean] ../translate/ghdldrv/ghdl: compilation error -Indeed, the `"="` operator is defined in both packages, and both -are visible at the place it is used. The first declaration is an -implicit one, which occurs when the `std_logic_vector` type is -declared and is an element to element comparison, the second one is an -explicit declared function, with the semantic of an unsigned comparison. +Indeed, the `"="` operator is defined in both packages, and both are visible at the place it is used. The first declaration is an implicit one, which occurs when the `std_logic_vector` type is declared and is an element to element comparison, the second one is an explicit declared function, with the semantic of an unsigned comparison. -With some analyser, the explicit declaration has priority over the implicit -declaration, and this design can be analyzed without error. However, this -is not the rule given by the VHDL LRM, and since GHDL follows these rules, +With some analyser, the explicit declaration has priority over the implicit declaration, and this design can be analyzed without error. However, this is not the rule given by the VHDL LRM, and since GHDL follows these rules, it emits an error. -You can force GHDL to use this rule with the *-fexplicit* option. -:ref:`GHDL_options`, for more details. - -However it is easy to fix this error, by using a selected name: +You can force GHDL to use this rule with the *-fexplicit* option (see :ref:`GHDL_options` for further details). However it is easy to fix this error, by using a selected name: .. code-block:: VHDL @@ -1240,9 +735,7 @@ However it is easy to fix this error, by using a selected name: val <= v; end fixed_bad; - -It is better to only use the standard packages defined by IEEE, which -provides the same functionalities: +It is better to only use the standard packages defined by IEEE, which provides the same functionalities: .. code-block:: VHDL @@ -1269,14 +762,8 @@ provides the same functionalities: val <= std_logic_vector (v); end good; - -IEEE math packages -================== - .. index:: Math_Real .. index:: Math_Complex -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 c0117833f..3173a6c61 100644 --- a/doc/using/QuickStartGuide.rst +++ b/doc/using/QuickStartGuide.rst @@ -9,7 +9,7 @@ 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: +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 @@ -31,23 +31,28 @@ To illustrate the large purpose of `VHDL`, here is a commented `'Hello world'` p end process; end behaviour; -Suppose this program is contained in a file named :file:`hello.vhdl`. 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`. +.. TIP:: Both :samp:`.vhdl` and :samp:`.vhd` extensions are used for VHDL source files, while :samp:`.v` is used for Verilog. -.. TIP:: If a GCC/LLVM variant of `GHDL` is used, this command generates a file :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created on Windows. +.. TODO:: 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 IEEE 1076-2008 Standard defines ASCII (7-bit encoding) or ISO Latin-1 (ISO-8859-1) as default. GHDL has a relaxing rule :samp:`--mb` (multi byte) to allow UTF-8 or other encodings in comments. Please see the MB description for details. -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. +- 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`. -Last, launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on the screen:: +.. WARNING:: If a GCC/LLVM variant of `GHDL` is used: - Hello world! - -.. TIP:: If a GCC/LLVM variant of `GHDL` is used, an executable program called :file:`hello_world` is generated at this step. This can can be run directly: :samp:`./hello_world`. + * `Analysis` generates a file, :file:`hello.o`, which is the object file corresponding to your `VHDL` program. This is not created on Windows. + * An aditional step is required; 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. This wil generate an executable binary named :file:`hello_world`. + * :option:`-e` can be bypassed with mcode, but you can still use it to check for some elaboration problems. + +- Last, launch the simulation running :samp:`ghdl -r hello_world` in the `shell`. The result of the simulation will be shown on the screen:: + Hello world! + +.. TIP:: If a GCC/LLVM variant of `GHDL` is used, :option:`-r` is just a passthrough to the binary generated in the `elaboration`. Therefore, the executable can be run directly, :samp:`./hello_world`. See :ref:`Run_command` for more informartion. + 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 the :file:`adder.vhdl` file: +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 @@ -66,15 +71,7 @@ a `full adder <https://en.wikipedia.org/wiki/Adder_(electronics)#Full_adder>`_ d co <= (i0 and i1) or (i0 and ci) or (i1 and ci); end rtl; - -You can analyze this design file: - -.. code-block:: shell - - $ ghdl -a adder.vhdl - - -You can try to execute the `adder` design, but this is useless, since nothing externally visible will happen. In order to check this full adder, a 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: +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 @@ -137,173 +134,65 @@ You can try to execute the `adder` design, but this is useless, since nothing ex end behav; -As usual, you should analyze the design: - -.. code-block:: shell - - $ ghdl -a adder_tb.vhdl - -Then elaborate the testbench: +As usual, you should analyze the design, :samp:`ghdl -a adder_tb.vhdl`. -.. code-block:: shell +.. 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. - $ ghdl -e adder_tb +Now, it is time to run the testbench, :samp:`ghdl -r adder_tb`, and check the result on screen:: -You do not need to specify which object files are required: GHDL knows them and automatically adds them. Now, it is time to run the testbench: - -.. code-block:: shell - - $ ghdl -r adder_tb adder_tb.vhdl:52:7:(assertion note): end of test -If your design is rather complex, you'd like to inspect signals. Signals value can be dumped using multiple formats. The resulting file can be read with a wave viewer such as GTKWave. First, you should simulate your design and dump a waveform file: - -.. code-block:: shell +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/>`_. - $ ghdl -r adder_tb --vcd=adder.vcd - -Then, you may now view the waves: - -.. code-block:: shell - - $ gtkwave adder.vcd - -See :ref:`Simulation_options`, for more details on the :option:`--vcd` option and -other runtime options. +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: :samp:`ghdl -r adder_tb --vcd=adder.vcd`. Then, you can view the dump: :samp:`gtkwave adder.vcd`. +See :ref:`simulation_options`, for more details on other runtime options. Starting with a design ====================== -Unless you are only studying VHDL, you will work with bigger 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 -http://ghdl.free.fr/dlx.tar.gz - -First, untar the sources: - -.. code-block:: shell - - $ tar zxvf dlx.tar.gz - - -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 - - -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: - -.. code-block:: shell +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>`_ . - $ ghdl -i --workdir=work *.vhdl +- First, untar the sources: :samp:`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. -and making a design: - -.. code-block:: shell - - $ ghdl -m --workdir=work dlx_test_behaviour - - -Before this second stage, GHDL knows all the design units of the DLX, -but no one have been analyzed. The make command of GHDL analyzes and -elaborates a design. This creates many files in the :file:`work/` -directory, and the :file:`dlx_test_behaviour` executable in the current -directory. - -The simulation needs to have a DLX program contained in the file -:file:`dlx.out`. This memory image will be be loaded in the DLX memory. -Just take one sample: - -.. code-block:: shell - - $ cp test_loop.out dlx.out - - -And you can run the test suite: - -.. code-block:: shell - - $ 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 - - -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: - -.. code-block:: shell - - $ ghdl -r --workdir=work dlx_test_behaviour --assert-level=note - + .. code-block:: shell -With this option, the program stops just after the previous message:: + $ cd dlx + $ mkdir work - dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction - encountered, execution halted - error: assertion failed +- 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. -If you want to make room on your hard drive, you can either: +.. 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`. -* clean the design library with the GHDL command: +- 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 - $ 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: - - .. code-block:: shell + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted - $ 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: +- 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 - $ rm -rf work + dlx-behaviour.vhdl:395:11:(assertion note): TRAP instruction + encountered, execution halted + error: assertion failed - Only the executable is kept. If you want to rebuild the design, create - the :file:`work/` directory, import the sources, and make the design. +.. TIP:: If you want to make room on your hard drive, you can either: -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:: - - --ieee=synopsys -fexplicit + * 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. -See :ref:`IEEE_library_pitfalls`, for more details. +.. 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 :ref:`IEEE_library_pitfalls`, for more details. Further examples ======================= diff --git a/doc/using/Simulation.rst b/doc/using/Simulation.rst index 041962b05..11ace067c 100644 --- a/doc/using/Simulation.rst +++ b/doc/using/Simulation.rst @@ -1,13 +1,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 @@ -77,45 +76,52 @@ all options available, including the debugging one. Display the time and delta cycle number as simulation advances. +.. option:: --unbuffered -.. option:: --disp-tree[=<KIND>] + Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO). - .. index:: display design hierarchy +.. option:: --psl-report=<FILENAME> - Display the design hierarchy as a tree of instantiated design entities. - This may be useful to understand the structure of a complex - design. `KIND` is optional, but if set must be one of: + Write a report for PSL assertions and coverage at the end of + simulation. The file is written using the JSON format, but still + being human readable. - * none - Do not display hierarchy. Same as if the option was not present. +.. option:: --sdf=<PATH>=<FILENAME> - * inst - Display entities, architectures, instances, blocks and generates statements. + Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`. - * proc - Like :samp:`inst` but also display processes. + `PATH` is a path of instances, separated with :samp:`.` or :samp:`/`. + Any separator can be used. Instances are component instantiation labels, + generate labels or block labels. Currently, you cannot use an indexed name. - * port - Like :samp:`proc` but display ports and signals too. - If `KIND` is not specified, the hierarchy is displayed with the - :samp:`port` mode. + Specifying a delay:: -.. option:: --no-run + --sdf=min=<PATH>=<FILENAME> + --sdf=typ=<PATH>=<FILENAME> + --sdf=max=<PATH>=<FILENAME> - Do not simulate, only elaborate. This may be used with - :option:`--disp-tree` to display the tree without simulating the whole - design. + If the option contains a type of delay, that is :samp:`min=`, + :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum, + typical or maximum values. If the option does not contain a type of delay, + the annotator use the typical delay. -.. option:: --unbuffered + See :ref:`Backannotation`, for more details. - Disable buffering on stdout, stderr and files opened in write or append mode (TEXTIO). +.. option:: --help + + Display a short description of the options accepted by the runtime library. + +.. _export_waves: + +Export waveforms +============ .. option:: --read-opt-file=<FILENAME> Filter signals to be dumped to the wave file according to the wave option file provided. - Here is a description of the wave option file format currently supported : + Here is a description of the wave option file format currently supported :: $ version = 1.1 # Optional @@ -219,39 +225,47 @@ all options available, including the debugging one. Contrary to VCD files, any VHDL type can be dumped into a GHW file. -.. option:: --psl-report=<FILENAME> - - Write a report for PSL assertions and coverage at the end of - simulation. The file is written using the JSON format, but still - being human readable. - -.. option:: --sdf=<PATH>=<FILENAME> +.. TODO:: - Do VITAL annotation on `PATH` with SDF file :file:`FILENAME`. + - :samp:` --vcd-nodate do not write date in VCD file` + - Is interactive simulation only possible with VCD? Can't it be done with either FST or GHW? + - `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 design hierarchy +============ + +.. option:: --disp-tree[=<KIND>] - `PATH` is a path of instances, separated with :samp:`.` or :samp:`/`. - Any separator can be used. Instances are component instantiation labels, - generate labels or block labels. Currently, you cannot use an indexed name. + .. index:: display design hierarchy - Specifying a delay:: + Display the design hierarchy as a tree of instantiated design entities. + This may be useful to understand the structure of a complex + design. `KIND` is optional, but if set must be one of: - --sdf=min=<PATH>=<FILENAME> - --sdf=typ=<PATH>=<FILENAME> - --sdf=max=<PATH>=<FILENAME> + * none + Do not display hierarchy. Same as if the option was not present. - If the option contains a type of delay, that is :samp:`min=`, - :samp:`typ=` or :samp:`max=`, the annotator use respectively minimum, - typical or maximum values. If the option does not contain a type of delay, - the annotator use the typical delay. + * inst + Display entities, architectures, instances, blocks and generates statements. - See :ref:`Backannotation`, for more details. + * proc + Like :samp:`inst` but also display processes. -.. option:: --help + * port + Like :samp:`proc` but display ports and signals too. + If `KIND` is not specified, the hierarchy is displayed with the + :samp:`port` mode. - Display a short description of the options accepted by the runtime library. +.. option:: --no-run + 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. + +.. TODO:: + * The json format is not documented, except it should be self-documented. Maybe worth adding a small example ? + * The XML format (for --file-to-xml) is not documented and it may change as it shows internal stuff. :samp:`--file-to-xml FILEs Dump AST in XML` + Debugging VHDL programs -======================= +============ .. index:: debugging |