generic: Refactor for faster performance

This won't affect Python-built arches significantly; but will be useful
for the future 'viaduct' functionality where generic routing graphs can
be built on the C++ side; too.

Signed-off-by: gatecat <gatecat@ds0.me>

1 files changed, 21 insertions, 14 deletions

diff --git a/docs/generic.md b/docs/generic.md
index 0562bed3..96db872e 100644
--- a/docs/generic.md
+++ b/docs/generic.md
@@ -12,35 +12,42 @@ will be worked on in the future.
 
 ## Python API
 
-All identifiers (`IdString`) are automatically converted to
-and from a Python string, so no manual conversion is required.
+All identifiers (`IdString`, `IdStringList`, `WireId`, `PipId`, and `BelId`) are
+automatically converted to and from a Python string, so no manual conversion is
+required.
+
+`IdStringList`s will be most efficient if strings can be split according to a
+separator (currently fixed to `/`), as only the components need be stored 
+in-memory. For example; instead of needing to store an entire pip name
+`X33/Y45/V4A_TO_A6` which scales badly for large numbers of pips; the strings
+`X33`, `Y45` and `V4A_TO_A6` are stored.
 
 Argument names are included in the Python bindings,
 so named arguments may be used.
 
-### void addWire(IdString name, IdString type, int x, int y);
+### void addWire(IdStringList name, IdString type, int x, int y);
 
 Adds a wire with a name, type (for user purposes only, ignored by all nextpnr code other than the UI) to the FPGA description. x and y give a nominal location of the wire for delay estimation purposes. Delay estimates are important for router performance (as the router uses an A* type algorithm), even if timing is not of importance.
 
-### addPip(IdString name, IdString type, IdString srcWire, IdString dstWire, float delay, Loc loc);
+### addPip(IdStringList name, IdString type, WireId srcWire, WireId dstWire, float delay, Loc loc);
 
 Adds a pip (programmable connection between two named wires). Pip delays that correspond to delay estimates are important for router performance (as the router uses an A* type algorithm), even if timing is otherwise not of importance.
 
 Loc is constructed using `Loc(x, y, z)`. 'z' for pips is only important if region constraints (e.g. for partial reconfiguration regions) are used.
 
-### void addBel(IdString name, IdString type, Loc loc, bool gb, bool hidden);
+### void addBel(IdStringList name, IdString type, Loc loc, bool gb, bool hidden);
 
 Adds a bel to the FPGA description. Bel type should match the type of cells in the netlist that are placed at this bel (see below for information on special bel types supported by the packer). Loc is constructed using `Loc(x, y, z)` and must be unique. If `hidden` is true, then the bel will not be included in utilisation reports (e.g. for routing/internal use bels).
 
-### void addBelInput(IdString bel, IdString name, IdString wire);
-### void addBelOutput(IdString bel, IdString name, IdString wire);
-### void addBelInout(IdString bel, IdString name, IdString wire);
+### void addBelInput(BelId bel, IdString name, WireId wire);
+### void addBelOutput(BelId bel, IdString name, WireId wire);
+### void addBelInout(BelId bel, IdString name, WireId wire);
 
 Adds an input, output or inout pin to a bel, with an associated wire. Note that both `bel` and `wire` must have been created before calling this function.
 
-### void addGroupBel(IdString group, IdString bel);
-### void addGroupWire(IdString group, IdString wire);
-### void addGroupPip(IdString group, IdString pip);
+### void addGroupBel(IdString group, BelId bel);
+### void addGroupWire(IdString group, WireId wire);
+### void addGroupPip(IdString group, PipId pip);
 ### void addGroupGroup(IdString group, IdString grp);
 
 Add a bel, wire, pip or subgroup to a group, which will be created if it doesn't already exist. Groups are purely for visual presentation purposes in the user interface and are not used by any place-and-route algorithms.
@@ -56,9 +63,9 @@ Add a graphic element to a _decal_, a reusable drawing that may be used to repre
 
 Sets the decal ID and offset for a wire, bel, pip or group in the UI.
 
-### void setWireAttr(IdString wire, IdString key, const std::string &value);
-### void setPipAttr(IdString pip, IdString key, const std::string &value);
-### void setBelAttr(IdString bel, IdString key, const std::string &value);
+### void setWireAttr(WireId wire, IdString key, const std::string &value);
+### void setPipAttr(PipId pip, IdString key, const std::string &value);
+### void setBelAttr(BelId bel, IdString key, const std::string &value);
 
 Sets an attribute on a wire, pip or bel. Attributes are displayed in the tree view in the UI, but have no bearing on place-and-route itself.