docs: Add Python API documentation

Signed-off-by: David Shah <dave@ds0.me>

1 files changed, 87 insertions, 0 deletions

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)
+