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 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. 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 PortRefs 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

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

4.2 KiB Raw Permalink Blame History