GHDL

https://ghdl.github.io/ghdl
Admin
GHDL is an open-source analyzer, compiler, simulator, and synthesizer for the VHDL hardware...
Tokens:937,007
Snippets:8,214
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### BlockConfiguration Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Configuration.html

An example showing the VHDL syntax for a block configuration.

```vhdl
for rtl
--  ^^^    <- Block
end for;
```

--------------------------------

### ConfigurationInstantiation Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Concurrent.html

Example showing the label and configuration components of a configuration instantiation.

```vhdl
  inst : configuration Counter;
--^^^^                            <- Label
--                     ^^^^^^^    <- Configuration
```

--------------------------------

### PackageReferenceSymbol Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Symbol.html

Example showing a package reference in VHDL code.

```vhdl
use ieee.numeric_std;
--  ^^^^^^^^^^^^^^^^

```

--------------------------------

### Bash: Configure vendor installation directories in config.sh

Source: https://ghdl.github.io/ghdl/_sources/getting.rst.txt

Set the installation directories for each vendor tool in the config.sh file. Use an empty string "" for tools not installed.

```Bash
declare -A InstallationDirectory
InstallationDirectory[AlteraQuartus]="/opt/Altera/16.0"
InstallationDirectory[IntelQuartus]="/opt/intelFPGA/20.1"
InstallationDirectory[LatticeDiamond]="/opt/Diamond/3.10_x64"
InstallationDirectory[OSVVM]="/home/<user>/git/GitHub/OSVVM"
InstallationDirectory[UVVM]="/home/<user>/git/GitHub/UVVM"
InstallationDirectory[XilinxISE]="/opt/Xilinx/14.7"
InstallationDirectory[XilinxVivado]="/opt/Xilinx/Vivado/2020.2"
```

--------------------------------

### RecordElementSymbol VHDL Example

Source: https://ghdl.github.io/ghdl/_modules/pyVHDLModel/Symbol.html

Example showing a reference to a record element.

```VHDL
r := (a => '1', b => '0');
--    ^                      <- Name
```

--------------------------------

### AllInstantiationList VHDL Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Configuration.html

Example of an instantiation list naming all instances of a component in VHDL.

```vhdl
for all : comp use entity work.sub(behav);
--  ^^^                                      <- the instantiation list
```

--------------------------------

### ModeViewSymbol Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Symbol.html

Example showing a mode view reference in a VHDL port declaration.

```vhdl
port (p : view MyView);
--          ^^^^^^

```

--------------------------------

### Install GHDL

Source: https://ghdl.github.io/ghdl/_sources/development/building/index.rst.txt

Install the compiled GHDL executable to the location specified during the configuration step.

```bash
$ make install
```

--------------------------------

### Get_Comment_Start

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/libghdl/file_comments.html

Gets the start position of a comment. Returns the position of the comment's first character.

```APIDOC
## Get_Comment_Start

### Description
Gets the start position of a comment. Returns the position of the comment's first character.

### Function
Get_Comment_Start(File: SourceFileEntry, Idx: Comment_Index) -> SourcePtr

### Parameters
- **File** (SourceFileEntry) - Required - Source file for node
- **Idx** (Comment_Index) - Required - Comment index

### Returns
- **SourcePtr** - The position of the comment's first character.
```

--------------------------------

### Install pyGHDL from git with pip using ghdl version hash

Source: https://ghdl.github.io/ghdl/quick_start/python/index.html

pyGHDL is not distributed through PyPI. Use `ghdl version hash` to get the commit hash of the installed binary and pass it to pip's git URL. Installing from `master` is discouraged because it may contain changes to the internal AST.

```bash
pip install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash)


```

--------------------------------

### _initialize()

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.libghdl.html

Locate and load the `libghdl` shared library.

```APIDOC
## pyGHDL.libghdl._initialize()

### Description
Locate and load the `libghdl` shared library.

### Method
Function

### Signature
`_initialize()`

### Parameters
None

### Returns
The loaded shared library.

### Raises
- **LibGHDLException** – If the shared library cannot be found.

```

--------------------------------

### Install pyGHDL from git with matching commit hash

Source: https://ghdl.github.io/ghdl/_sources/quick_start/python/index.rst.txt

Install pyGHDL from the git repository using the commit hash of the installed GHDL binary. The version of the sources must be compatible with the installed GHDL and its shared library libghdl. Installing from master is discouraged because it may contain changes to the internal AST.

```shell
pip install git+https://github.com/ghdl/ghdl.git@$(ghdl version hash)
```

--------------------------------

### __init__(_node_ , _name_ , _documentation =None_)

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.InterfaceItem.html

Initializes a package in a generic clause.

```APIDOC
## __init__(_node_ , _name_ , _documentation =None_)

### Description
Initializes a package in a generic clause.

### Parameters
- **node** (`TypeVar`(`Iir`, bound= `c_int`)) - Required - The IIR node this object was translated from.
- **name** (`str`) - Required - The generic package’s identifier.
- **documentation** (`str`) - Optional - The documentation comment associated with this declaration.

### Returns
- **Return type**: None

```

--------------------------------

### Application.__init__()

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.cli.dom.html

Initializes the application.

```APIDOC
## Application.__init__()

### Description
Initializes the application.

### Method
__init__

### Parameters
None

### Returns
None
```

--------------------------------

### EntityAspectConfiguration VHDL Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Configuration.html

Example of a VHDL configuration aspect usage.

```vhdl
use configuration work.cfg;
--                ^^^^^^^^    <- Configuration
```

--------------------------------

### Application.HandleInfo(_args_)

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.cli.dom.html

Handle the `version` sub-command: print copyright, license and authors.

```APIDOC
## Application.HandleInfo(_args_)

### Description
Handle the `version` sub-command: print copyright, license and authors.

### Method
HandleInfo

### Parameters
- **args** – The parsed arguments, unused.

### Returns
None
```

--------------------------------

### Application.HandleHelp(_args_)

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.cli.dom.html

Handle the `help` sub-command: print the help page of a command, or the overview.

```APIDOC
## Application.HandleHelp(_args_)

### Description
Handle the `help` sub-command: print the help page of a command, or the overview.

### Method
HandleHelp

### Parameters
- **args** – The parsed arguments, carrying the optional command name.

### Returns
None
```

--------------------------------

### SlicedName VHDL Example

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/dom/Name.html

Example of a slice construct following a name.

```VHDL
arr(7 downto 0)
-- ^^^^^^^^^^^^
```

--------------------------------

### Application Initialization

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/cli/dom.html

Initializes the application, sets up the argument parser with a custom help formatter, and configures log message formats for different severity levels.

```python
def __init__(self):
    """
    Initializes the application.
    """
    super().__init__()

    # Initialize DOM with an empty design
    # --------------------------------------------------------------------------
    self._design = Design()

    # Call the constructor of the ArgParseMixin
    # --------------------------------------------------------------------------
    textWidth = min(max(self.Width, 80), 160)
    description = dedent("""
        Application to test pyGHDL's DOM API.
        """)
    epilog = "\n".join(
        wrap(
            dedent("""
                pyGHDL is a Python binding for libghdl.
                """),
            textWidth,
            replace_whitespace=False,
        )
    )

    class HelpFormatter(RawDescriptionHelpFormatter):
        """
        Help formatter widening argparse's output to the terminal.
        """

        def __init__(self, *args, **kwargs):
            """
            Initializes the formatter with a wider help column and line width.

            :param args:   Positional arguments passed on to :class:`~argparse.RawDescriptionHelpFormatter`.
            :param kwargs: Keyword arguments passed on, with the width settings overridden.
            """
            kwargs["max_help_position"] = 30
            kwargs["width"] = textWidth
            super().__init__(*args, **kwargs)

    ArgParseHelperMixin.__init__(
        self,
        description=description,
        epilog=epilog,
        formatter_class=HelpFormatter,
        add_help=False,
    )

    # Change error and warning reporting
    # --------------------------------------------------------------------------
    self._LOG_MESSAGE_FORMAT__[Severity.Fatal] = "{DARK_RED}[FATAL] {message}{NOCOLOR}"
    self._LOG_MESSAGE_FORMAT__[Severity.Error] = "{RED}[ERROR] {message}{NOCOLOR}"
    self._LOG_MESSAGE_FORMAT__[Severity.Warning] = "{YELLOW}[WARNING] {message}{NOCOLOR}"
    self._LOG_MESSAGE_FORMAT__[Severity.Normal] = "{GRAY}{message}{NOCOLOR}"
```

--------------------------------

### OthersInstantiationList example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Configuration.html

Example showing the VHDL syntax for an instantiation list that targets components not configured elsewhere.

```vhdl
for others : comp use entity work.sub(behav);
--  ^^^^^^                                      <- the instantiation list
```

--------------------------------

### SimpleName VHDL Example

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/dom/Name.html

Example of a simple identifier name in VHDL.

```VHDL
ieee
```

--------------------------------

### PowerShell: Configure vendor installation directories in config.psm1

Source: https://ghdl.github.io/ghdl/_sources/getting.rst.txt

Set the installation directories for each vendor tool in the config.psm1 file. Use an empty string "" for tools not installed.

```PowerShell
$InstallationDirectory = @{
  "AlteraQuartus" =   "C:\Altera\16.0";
  "IntelQuartus" =    "C:\Altera\20.1";
  "LatticeDiamond" =  "C:\Lattice\Diamond\3.10_x64";
  "XilinxISE" =       "C:\Xilinx\14.7\ISE_DS";
  "XilinxVivado" =    "C:\Xilinx\Vivado\2020.2";
  "OSVVM" =           "C:\git\GitHub\OSVVM";
  "UVVM" =            "C:\git\GitHub\UVVM"
}
```

--------------------------------

### Initialize VHDL Document (pyVHDLModel.Document.__init__)

Source: https://ghdl.github.io/ghdl/_modules/pyVHDLModel.html

Initializes a VHDL document with a path, optional documentation, VHDL version (default VHDL2008), library, and parent. Sets up internal dictionaries for design units, contexts, configurations, entities, architectures, packages, package bodies, and PSL verification units/properties/modes, plus dependency and compile-order graph vertices.

```python
def __init__(
		self,
		path:          Path,
		documentation: Nullable[str] = None,
		vhdlVersion:   VHDLVersion = VHDLVersion.VHDL2008,
		library:       Nullable[Library] = None,
		parent:        Nullable[ModelEntity] = None
	) -> None:
		"""
		Initializes a VHDL document.

		:param path:          Path to the document. ``None`` if in-memory document.
		:param documentation: The documentation comment associated with this declaration.
		:param vhdlVersion:   VHDL version used for analyzing this source file.
		:param library:       VHDL library used for analyzing the source file's content into.
		:param parent:        The parent model entity of this entity.
		"""
		super().__init__(parent)
		DocumentedEntityMixin.__init__(self, documentation)

		self._path =                   path
		self._vhdlVersion =            vhdlVersion
		self._library =                library
		self._designUnits =            []
		self._contexts =               {}
		self._configurations =         {}
		self._entities =               {}
		self._architectures =          {}
		self._packages =               {}
		self._packageBodies =          {}
		self._verificationUnits =      {}
		self._verificationProperties = {}
		self._verificationModes =      {}

		self._dependencyVertex =   None
		self._compileOrderVertex = None
```

--------------------------------

### Run the design

Source: https://ghdl.github.io/ghdl-cosim/vhpidirect/grt.html

Execution of the built binary and its expected output.

```bash
$ ./test_grt
Status is  0
Root instance name: counter
```

--------------------------------

### ConfigurationSymbol VHDL Example

Source: https://ghdl.github.io/ghdl/_modules/pyVHDLModel/Symbol.html

Demonstrates a reference to a configuration in a component instantiation.

```VHDL
for U1 : comp use configuration work.cfg;
--                              ^^^^^^^^    <- Name
```

--------------------------------

### Compile vendor libraries in Bash (compile-altera.sh --all)

Source: https://ghdl.github.io/ghdl/getting.html

Steps for compiling vendor libraries in Bash: change to the simulation working directory, run one or more compile scripts with the --all flag, then list the created vendor directories. The scripts are installed in /usr/local/lib/ghdl/vendors and create directories named altera, intel, lattice, osvvm, uvvm, and xilinx-vivado in the current working directory.

```bash
$ cd <MySimulationFolder>

```

```bash
$ /usr/local/lib/ghdl/vendors/compile-altera.sh --all
$ /usr/local/lib/ghdl/vendors/compile-intel.sh --all
$ /usr/local/lib/ghdl/vendors/compile-lattice.sh --all
$ /usr/local/lib/ghdl/vendors/compile-uvvm.sh --all
$ /usr/local/lib/ghdl/vendors/compile-xilinx-vivado.sh --all

```

```bash
$ ls -ahl
...
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:41 altera
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:42 intel
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:42 lattice
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 osvvm
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:58 uvvm
drwxr-xr-x  2 <user> <group>  56K Mar 09 17:48 xilinx-vivado

```

--------------------------------

### CompositeModeViewElement VHDL Example

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/dom/InterfaceItem.html

An example of a VHDL view declaration using CompositeModeViewElement.

```VHDL
view OuterView of OuterRecord is
  b : view InnerView;
end view;
```

--------------------------------

### VHDL AttributeName Example

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/dom/Name.html

Example of a name following tick-notation as represented by AttributeName.

```VHDL
arr'length
-- ^^^^^^^
```

--------------------------------

### VHDL SelectedName Example

Source: https://ghdl.github.io/ghdl/_modules/pyGHDL/dom/Name.html

Example of a name following dot-notation as represented by SelectedName.

```VHDL
rec.elem
-- ^^^^^
```

--------------------------------

### Application.HandlePretty(_args_)

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.cli.dom.html

Handle the `pretty` sub-command: analyze the selected sources and pretty-print the resulting model.

```APIDOC
## Application.HandlePretty(_args_)

### Description
Handle the `pretty` sub-command: analyze the selected sources and pretty-print the resulting model. A file is analyzed on its own; a directory is scanned, and each subdirectory is treated as a library of that name. The time _libghdl_ spent parsing and the time the translation took are reported per file.

### Method
HandlePretty

### Parameters
- **args** – The parsed arguments, carrying the selected files, directory and default library.

### Returns
None
```

--------------------------------

### __init__(_node_, _prefix_)

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Name.html

Initializes an all name.

```APIDOC
## __init__(_node_, _prefix_)

### Description
Initializes an all name.

### Parameters
- **node** (`TypeVar`(`Iir`, bound= `c_int`)) - Required - The IIR node this object was translated from.
- **prefix** (`Name`) - Required - Reference to the name's prefix, or `None` for a simple name.

### Returns
- **None**
```

--------------------------------

### Procedure Instantiation Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Subprogram.html

An example of a VHDL procedure instantiation that can be represented by the ProcedureInstantiation class.

```vhdl
procedure my_proc is new work.pkg.generic_proc generic map (T => integer);
```

--------------------------------

### Configuration.__init__

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.DesignUnit.html

Initializes a configuration declaration with the given IIR node, identifier, entity, block configuration, context items, and documentation.

```APIDOC
## Configuration.__init__

### Description
Initializes a configuration declaration.

### Method
Constructor

### Parameters
- **node** (Iir) - Required - The IIR node this object was translated from.
- **identifier** (str) - Required - The configuration's identifier.
- **entity** (EntitySymbol) - Required - Reference to the entity this configuration configures.
- **blockConfiguration** (BlockConfiguration) - Required - The configuration of the entity's architecture.
- **contextItems** (Iterable[Context]) - Optional - List of all context items (library, use and context clauses).
- **documentation** (str) - Optional - The documentation comment associated with this declaration.

### Return Type
None
```

--------------------------------

### Function Instantiation Example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Subprogram.html

An example of a VHDL function instantiation that can be represented by the FunctionInstantiation class.

```vhdl
function add_int is new work.pkg.generic_add generic map (T => integer);
```

--------------------------------

### PackageInstantiation.__init__

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.DesignUnit.html

Initializes a package instantiation with the given IIR node, identifier, uninstantiated package name, context items, generic association items, and documentation.

```APIDOC
## PackageInstantiation.__init__

### Description
Initializes a package instantiation.

### Method
Constructor

### Parameters
- **node** (Iir) - Required - The IIR node this object was translated from.
- **identifier** (str) - Required - The instantiated package's identifier.
- **uninstantiatedPackageName** (Symbol) - Required - The name of the uninstantiated generic package.
- **contextItems** (Iterable[LibraryClause | UseClause | ContextReference]) - Optional - List of all context items (library, use and context clauses).
- **genericAssociationItems** (Iterable[GenericAssociationItem]) - Optional - List of all generic associations in the generic map aspect.
- **documentation** (str) - Optional - The documentation comment associated with this declaration.

### Return Type
None
```

--------------------------------

### File declaration example

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.Object.html

Example of a VHDL file declaration represented by the pyGHDL.dom.Object.File class.

```vhdl
file INPUT : TEXT;
```

--------------------------------

### VHDL Package Instantiation Syntax

Source: https://ghdl.github.io/ghdl/pyGHDL/pyGHDL.dom.DesignUnit.html

An example of the VHDL syntax for instantiating a generic package, highlighting the identifier and package reference.

```vhdl
package p is new gp generic map (N => 1);
--      ^                                   <- Identifier
--               ^^                         <- PackageReference
```
Tokens:
Raw