From 4c1118d130c5b2dd8aef5ef486138db002dcfda7 Mon Sep 17 00:00:00 2001 From: 1138-4EB <1138-4EB@users.noreply.github.com> Date: Sun, 19 Feb 2017 08:12:30 +0100 Subject: Removed numbers from folder names. --- doc/1_Using/InvokingGHDL.rst | 1281 --------------------------------------- doc/1_Using/QuickStartGuide.rst | 359 ----------- doc/1_Using/Simulation.rst | 292 --------- 3 files changed, 1932 deletions(-) delete mode 100644 doc/1_Using/InvokingGHDL.rst delete mode 100644 doc/1_Using/QuickStartGuide.rst delete mode 100644 doc/1_Using/Simulation.rst (limited to 'doc/1_Using') diff --git a/doc/1_Using/InvokingGHDL.rst b/doc/1_Using/InvokingGHDL.rst deleted file mode 100644 index d4bcda438..000000000 --- a/doc/1_Using/InvokingGHDL.rst +++ /dev/null @@ -1,1281 +0,0 @@ -.. _USING:Invoking: - -************* -Invoking GHDL -************* - -The form of the :program:`ghdl` command is:: - - ghdl command [options...] - -The GHDL program has several commands. 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. - -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). - -Design building commands -================= - -The mostly used commands of GHDL are those to analyze and elaborate a design. - -Analysis command ----------------- - -.. 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:: - - ghdl -a -g my_design.vhdl - - -.. _Elaboration_command: - -Elaboration command -------------------- - -.. 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: - -* 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 - -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. - -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. - -.. _Run_command: - -Run command ------------ - -.. index:: run - -.. index:: -r command - -Run (or simulate) a design:: - - ghdl -r [options...] primary_unit [secondary_unit] [simulation_options...] - - -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. - -This command exists for three reasons: - -* You don't have 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. - -See :ref:`Simulation_and_runtime`, for details on options. - -Elaborate and run command -------------------------- - -.. 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...] - - -This 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 - -.. index:: --bind command - -Bind a design unit and prepare the link step:: - - ghdl --bind [options] primary_unit [secondary_unit] - - -This command is only available on GNU/Linux. - -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. - -.. _Link_command: - -Link command ------------- - -.. index:: linking - -.. index:: --link command - -Link an already bound design unit:: - - ghdl --link [options] primary_unit [secondary_unit] - -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. - -.. _List_link_command: - -List link command ------------------ - -.. index:: --list-link command - -Display files which will be linked:: - - ghdl --list-link primary_unit [secondary_unit] - -This command is only available on GNU/Linux. - -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. - -.. _Check_syntax_command: - -Check syntax command --------------------- - -.. index:: checking syntax - -.. index:: -s command - -Analyze files but do not generate code:: - - ghdl -s [options] files - -This command may be used to check the syntax of files. It does not update -the library. - -.. _Analyze_and_elaborate_command: - -Analyze and elaborate command ------------------------------ - -.. index:: Analyze and elaborate command - -.. index:: -c command - -Analyze files and elaborate them at the same time. - -On GNU/Linux:: - - ghdl -c [options] file... -e primary_unit [secondary_unit] - - -On Windows:: - - ghdl -c [options] file... -r primary_unit [secondary_unit] - - -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. - -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. - -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. - -The advantages over the traditional approach (analyze and then elaborate) are: - -* 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. - -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. - -This command is still experimental. In case of problems, you should go back -to the traditional way. - -.. _GHDL_Options: - -GHDL options -============ - -.. index:: IEEE 1164 - -.. index:: 1164 - -.. index:: IEEE 1076.3 - -.. 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. - - - -.. option::--work= - - .. index:: WORK library - - Specify the name of the :samp:`WORK` library. Analyzed units are always - placed in the library logically named :samp:`WORK`. With this option, - you can set its name. By default, the name is :samp:`work`. - - `GHDL` checks whether :samp:`WORK` is a valid identifier. Although being - more or less supported, the :samp:`WORK` identifier should not be an - extended identifier, since the filesystem may prevent it from correctly - working (due to case sensitivity or forbidden characters in filenames). - - `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 - option is not present, the :samp:`WORK` library is in the current - directory. The object files created by the compiler are always placed - in the same directory as the :samp:`WORK` library. - - 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 - .. index:: synopsys library - .. index:: mentor library - - Select the :samp:`IEEE` library to use. :samp:`VER` must be one of: - - none - Do not supply an `IEEE` library. Any library clause with the :samp:`IEEE` - identifier will fail, unless you have created by your own a library with - the `IEEE` name. - - standard - Supply an `IEEE` library containing only packages defined by - :samp:`ieee` standards. Currently, there are the multivalue logic system - packages :samp:`std_logic_1164` defined by IEEE 1164, the synthesis - packages , :samp:`numeric_bit` and :samp:`numeric_std` defined by IEEE - 1076.3, and the :samp:`vital` packages :samp:`vital_timing` and - :samp:`vital_primitives`, defined by IEEE 1076.4. The version of these - packages is defined by the VHDL standard used. See :ref:`VITAL_packages`, - for more details. - - synopsys - Supply the former packages and the following additional packages: - :samp:`std_logic_arith`, :samp:`std_logic_signed`, - :samp:`std_logic_unsigned`, :samp:`std_logic_textio`. - - These packages were created by some companies, and are popular. However - they are not standard packages, and have been placed in the `IEEE` - library without the permission from the :samp:`ieee`. - - mentor - Supply the standard packages and the following additional package: - :samp:`std_logic_arith`. The package is a slight variation of a definitely - not standard but widely mis-used package. - - 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 - library files. A library is searched in `DIRECTORY` and also in - `DIRECTORY/LIB/vVV` (where `LIB` is the name of the library and `VV` - the vhdl standard). - - The `WORK` library is always searched in the path specified by the - :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. - - -.. option:: -frelaxed-rules - - Within an object declaration, allow to reference the name (which - references the hidden declaration). This ignores the error in the - following code: - - .. code-block:: VHDL - - package pkg1 is - type state is (state1, state2, state3); - end pkg1; - - use work.pkg1.all; - package pkg2 is - constant state1 : state := state1; - end pkg2; - - Some code (such as Xilinx packages) have such constructs, which - are valid. - - (The scope of the :samp:`state1` constant start at the `constant` - word. Because the constant :samp:`state1` and the enumeration literal - :samp:`state1` are homograph, the enumeration literal is hidden in the - immediate scope of the constant). - - 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 - - Disable or enable checks of restriction on VITAL units. Checks are enabled - by default. - - Checks are performed only when a design unit is decorated by a VITAL attribute. - The VITAL attributes are :samp:`VITAL_Level0` and :samp:`VITAL_Level1`, both - declared in the :samp:`ieee.VITAL_Timing` package. - - 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,