.. _INTRO:Copyrights: Copyrights | Licenses ##################### - The GHDL front-end package ``std.textio``, and the runtime library ``GRT`` are given under :ref:`LIC:GPLv2`. - The documentation is given under :ref:`LIC:CC-BY-SA`. .. WARNING:: As a consequence of the runtime copyright, you are not allowed to distribute an executable produced by GHDL without allowing access to the VHDL sources. Please, send a comment (:ref:`requesting_enhancements`) if you don't like this policy. The following packages are copyrighted by third parties (see corresponding sources for more information): * These from library ``ieee`` are copyrighted by `Institute of Electrical and Electronics Engineers (IEEE) `__: * Since December 2019, standard and IEEE libraries are distributed under Apache 2.0 and available at `opensource.ieee.org/vasg/Packages `__. GHDL includes backports of those libraries for earlier revisions of the standard. * ``VITAL_Primitives``, ``VITAL_Timing`` and ``VITAL_Memory`` are not include in the open source distribution of IEEE (see `IEEE 1076.4 `__). * The following sources may be used and distributed without restriction, provided that the copyright statements are not removed from the files and that any derivative work contains the copyright notice. * ``synopsys`` directory: ``std_logic_arith``, ``std_logic_signed``, ``std_logic_unsigned`` and ``std_logic_textio`` are copyrighted by `Synopsys, Inc. `__ * ``mentor`` directory: ``std_logic_arith`` is copyrighted by `Mentor Graphics `__. .. _LIC:GPLv2: GNU GPLv2 ========= GHDL is copyright |copy| 2002 - 2022 Tristan Gingold. This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the `GNU General Public License `__ for more details. .. _LIC:CC-BY-SA: CC-BY-SA ======== This is a free documentation; you can redistribute it and/or modify it under the terms of the `Creative Commons Attribution-ShareAlike 4.0 `__ license. You are free to **share** (copy and redistribute the material in any medium or format) and/or **adapt** (remix, transform, and build upon the material for any purpose, even commercially). We cannot revoke these freedoms as long as you follow the these terms: - **Attribution**: you must provide the name of the creator and attribution parties (`more info `__), a copyright notice, a license notice, a disclaimer notice, a link to the material, a link to the license and indicate if changes were made (see `marking guide `__ and `more info `__). You may do so in any reasonable manner, but not in any way that suggests we endorse you or your use. - **ShareAlike**: if you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original. - **No additional restrictions**: you may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. See `CC-BY-SA-4.0 Legal Code `__ for more details. .. _LIC:contributors: List of Contributors ==================== ============================= =============================================================================================================== Contributor [#f1]_ Role ============================= =============================================================================================================== Baggett, Jonas signal selection Bertram, Felix VPI interface Davis, Brian Windows Mcode builds Drummond, Brian GCC 4.8.2 update, OSVVM port, some bugfixes Gingold, Tristan [#f2]_ **Sole author of GHDL as a whole** 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. Meißner, Torsten Property Specification Language (PSL): docs, tests, synthesis support Martinez-Corral, Unai [#f2]_ ghdl-cosim, setup-ghdl-ci, docs, docker/CI, MSYS2 packaging, building/testing on ARM, termux builds van Rantwijk, Joris Debian packaging ============================= =============================================================================================================== .. only:: html .. exec:: from helpers import createShields createShields('shields') Only those who mad
# Using the Python API

nextpnr provides Python bindings to its internal APIs to enable customisation of the FPGA CAD flow.

If you are interested in using Python to describe the FPGA rather than customise or explore the flow, see the [nextpnr Generic Architecture](generic.md) documentation.

## Running Python Scripts

Python scripts can be run at any point in the flow. The following command line arguments are used to run a script:

 - **--pre-pack script.py**: after reading the JSON, before packing
 - **--pre-place script.py**: after packing, before placement
 - **--pre-route script.py**: after placement, before routing
 - **--post-route script.py**: after routing, before bitstream generation

## Binding Overview

The internal `Context` object providing access to the FPGA architecture and netlist is exposed automatically to the script as a global variable `ctx`.

Internally, nextpnr uses a fast indexed string pool called `IdString`. This is automatically and transparently converted to/from Python strings by the Python binding layer. 

Likewise, the architecture identifiers `BelId`, `WireId` and `PipId` are also translated to/from Python strings containing the object name automatically.

To query the FPGA architecture, use the functions described in the [Architecture API documentation](archapi.md). Ranges can be iterated over in the same way as any other Python range.

## Netlist Access

### Accessing nets

There is a dictionary `ctx.nets` that provides access to all of the nets in a design by name. Each net item has the following fields:

 - `name`: name of the net
 - `wires`: a map of wires used by the net; from wire to the pip driving that wire
 - `driver`: a `PortRef` for the net's driving (source) port
 - `users`: a list of `PortRef`s for the net's sink ports
 - `attrs`: a read-only dictionary of attributes on the net

A `PortRef` has three fields:
    - `cell`: a reference to the cell the port is on
    - `port`: the name of the port
    - `budget`: the timing budget of the port

### Accessing cells

There is a dictionary `ctx.cells` that provides access to all of the cells in a design by name. Each cell item has the following fields:

 - `name`: name of the cell
 - `type`: type of the cell
 - `ports`: a read-only dictionary of ports on the cell. Each port has the following fields:
   - `name`: name of the port
   - `net`: reference to the connected net, or `None` if disconnected
   - `type`: direction of the port 
 - `params`: a read-only dictionary of parameters on the cell
 - `attrs`: a read-only dictionary of attributes on the cell
 - `bel`: the Bel the cell is placed on

Cells also have the following member functions:
 - `addInput(name)`: add a new input port with a given name
 - `addOutput(name)`: add a new output port with a given name
 - `addInout(name)`: add a new bidirectional port with a given name
 - `setParam(name, value)`: set a parameter on a cell to a given value
 - `unsetParam(name)`: remove a parameter from the cell
 - `setAttr(name, value)`: set an attribute on a cell to a given value
 - `unsetAttr(name)`: remove an attribute from the cell

The value given to `setParam` and `setAttr` should be a string of `[01xz]*` for four-state bitvectors and numerical values. Other values will be interpreted as a textual string. Textual strings of only `[01xz]* *` should have an extra space added at the end which will be stripped off and avoids any ambiguous cases between strings and four-state bitvectors.

### Creating Objects

`ctx` has two functions for creating new netlist objects. Both return the created object:
 - `createNet(name)`
 - `createCell(name, type)` (note this creates an empty cell, ports must be added separately)

### Other manipulations

`ctx` has some other helper functions for netlist manipulations:

 - `connectPort(netname, cellname, portname)`: connect a cell port to a net
 - `disconnectPort(cellname, portname)`: disconnect a cell port from its net
 - `ripupNet(netname)`: remove all routing from a net (but keep netlist connections intact)
 - `lockNetRouting(netname)`: set the routing of a net as fixed
 - `copyBelPorts(cellname, belname)`: replicate the port definitions of a Bel onto a cell (useful for creating standard cells, as `createCell` doesn't create any ports).

## Constraints

See the [constraints documentation](constraints.md)
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-08 13:52:19 +0000