From 6871bbba1bdc4332cf68e1494e3c6f1615fefbcb Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Fri, 24 Feb 2017 19:00:45 +0100 Subject: Files in the root not capitalized. Second chapter ready for first review: Invoking reordered, some content moved to Command Reference, information compacted, command shortcuts added to titles. Known features which are missing in the doc added to TODOs or to Roadmap. Add export subsections to Using/Simulation Directory structure described in Building --- doc/using/InvokingGHDL.rst | 831 ++++++++---------------------------------- doc/using/QuickStartGuide.rst | 201 +++------- doc/using/Simulation.rst | 108 +++--- 3 files changed, 265 insertions(+), 875 deletions(-) (limited to 'doc/using') 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 ` 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 `. -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 `) followed by the run command (see :ref:`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 `, 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 `), 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= - - .. index:: WORK library +.. option:: --work= 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= 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= 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= .. 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 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= Use :file:`PATH` as the prefix path to find commands and pre-installed (std and ieee) libraries. - -.. option:: --GHDL1= - - 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= - - 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= - - 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,