From 6bb098b4761ba6d5fbbda07b3dcb88356ece6ce1 Mon Sep 17 00:00:00 2001 From: David Shah Date: Thu, 19 Sep 2019 15:49:49 +0100 Subject: docs: Add Python API documentation Signed-off-by: David Shah --- docs/python.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 docs/python.md (limited to 'docs') diff --git a/docs/python.md b/docs/python.md new file mode 100644 index 00000000..d850300d --- /dev/null +++ b/docs/python.md @@ -0,0 +1,87 @@ +# 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) + -- cgit v1.2.3