Update docs with API changes

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

1 files changed, 160 insertions, 21 deletions

diff --git a/docs/archapi.md b/docs/archapi.md
index 0cd6632c..9e6b3a46 100644
--- a/docs/archapi.md
+++ b/docs/archapi.md
@@ -1,6 +1,35 @@
 Each architecture must implement the following types and APIs.
 
-The syntax `const_range<T>` is used to denote anything that has a `begin()` and `end()` method that return const forward iterators. This can be a `std::list<T>`, `std::vector<T>`, a (const) reference to those, or anything else that behaves in a similar way.
+Architectures can either inherit from `ArchAPI<ArchRanges>`, which is a pure virtual description of the architecture API; or `BaseArch<ArchRanges>` which provides some default implementations described below.
+
+`ArchRanges` is a `struct` of `using`s that allows arches to return custom range types. These ranges can be anything that has a `begin()` and `end()` method that return const forward iterators. This can be a `std::list<T>`, `std::vector<T>`, a (const) reference to those, or anything else that behaves in a similar way.
+
+The contents of `ArchRanges` is as follows:
+
+| Type                      | Range of                         |
+|---------------------------|----------------------------------|
+|`ArchArgsT`                | N/A (struct of device params)    |
+|`AllBelsRangeT`            | `BelId`                          |
+|`TileBelsRangeT`           | `BelId`                          |
+|`BelAttrsRangeT`           | std::pair<IdString, std::string> |
+|`BelPinsRangeT`            | `IdString`                       |
+|`AllWiresRangeT`           | `WireId`                         |
+|`DownhillPipRangeT`        | `PipId`                          |
+|`UphillPipRangeT`          | `PipId`                          |
+|`WireBelPinRangeT`         | `BelPin`                         |
+|`AllPipsRangeT`            | `PipId`                          |
+|`PipAttrsRangeT`           | std::pair<IdString, std::string> |
+|`AllGroupsRangeT`          | `GroupId`                        |
+|`GroupBelsRangeT`          | `BelId`                          |
+|`GroupWiresRangeT`         | `WireId`                         |
+|`GroupPipsRangeT`          | `PipId`                          |
+|`GroupGroupsRangeT`        | `GroupId`                        |
+|`DecalGfxRangeT`           | `GraphicElement`                 |
+|`CellTypeRangeT`           | `IdString`                       |
+|`BelBucketRangeT`          | `BelBucketRange`                 |
+|`BucketBelRangeT`          | `BelId`                          |
+
+The functions that return a particular type are described below
 
 archdefs.h
 ==========
@@ -84,6 +113,8 @@ Return the `ArchArgs` used to construct this object.
 
 Return an internal IdString representation of the ArchArgs that was used to construct this object.
 
+*BaseArch default: returns empty IdString*
+
 ### int getGridDimX() const
 
 Get grid X dimension. All bels and pips must have Y coordinates in the range `0 .. getGridDimX()-1` (inclusive).
@@ -100,17 +131,23 @@ Get Z dimension for the specified tile for bels. All bels with at specified X an
 
 Get Z dimension for the specified tile for pips. All pips with at specified X and Y coordinates must have a Z coordinate in the range `0 .. getTileDimZ(X,Y)-1` (inclusive).
 
+*BaseArch default: returns 1*
+
 ### char getNameDelimiter() const
 
 Returns a delimiter that can be used to build up bel, wire and pip names out of hierarchical components (such as tiles and sites) to avoid the high memory usage of storing full names for every object.
 
+*BaseArch default: returns ' '*
+
 Cell Methods
 -----------
 
-### const\_range\<IdString\> getCellTypes() const
+### CellTypeRangeT getCellTypes() const
 
 Get list of cell types that this architecture accepts.
 
+*BaseArch default: returns list derived from bel types set up by `init_cell_types()`*
+
 Bel Methods
 -----------
 
@@ -130,7 +167,7 @@ Get the X/Y/Z location of a given bel. Each bel must have a unique X/Y/Z locatio
 
 Lookup a bel by its X/Y/Z location.
 
-### const\_range\<BelId\> getBelsByTile(int x, int y) const
+### TileBelsRangeT getBelsByTile(int x, int y) const
 
 Return a list of all bels at the give X/Y location.
 
@@ -138,35 +175,49 @@ Return a list of all bels at the give X/Y location.
 
 Returns true if the given bel is a global buffer. A global buffer does not "pull in" other cells it drives to be close to the location of the global buffer.
 
+*BaseArch default: returns false*
+
 ### uint32\_t getBelChecksum(BelId bel) const
 
 Return a (preferably unique) number that represents this bel. This is used in design state checksum calculations.
 
+*BaseArch default: returns `std::hash` of `BelId` cast to `uint32_t`*
+
 ### void bindBel(BelId bel, CellInfo \*cell, PlaceStrength strength)
 
 Bind a given bel to a given cell with the given strength.
 
 This method must also update `cell->bel` and `cell->belStrength`.
 
+*BaseArch default: binds using `base_bel2cell`*
+
 ### void unbindBel(BelId bel)
 
 Unbind a bel.
 
 This method must also update `CellInfo::bel` and `CellInfo::belStrength`.
 
+*BaseArch default: unbinds using `base_bel2cell`*
+
 ### bool checkBelAvail(BelId bel) const
 
 Returns true if the bel is available. A bel can be unavailable because it is bound, or because it is exclusive to some other resource that is bound.
 
+*BaseArch default: returns `getBoundBelCell(bel) == nullptr`*
+
 ### CellInfo \*getBoundBelCell(BelId bel) const
 
 Return the cell the given bel is bound to, or nullptr if the bel is not bound.
 
+*BaseArch default: returns entry in `base_bel2cell`*
+
 ### CellInfo \*getConflictingBelCell(BelId bel) const
 
 If the bel is unavailable, and unbinding a single cell would make it available, then this method must return that cell.
 
-### const\_range\<BelId\> getBels() const
+*BaseArch default: returns `getBoundBelCell(bel)`*
+
+### AllBelsRangeT getBels() const
 
 Return a list of all bels on the device.
 
@@ -174,11 +225,13 @@ Return a list of all bels on the device.
 
 Return the type of a given bel.
 
-### const\_range\<std\:\:pair\<IdString, std::string\>\> getBelAttrs(BelId bel) const
+### BelAttrsRangeT getBelAttrs(BelId bel) const
 
 Return the attributes for that bel. Bel attributes are only informal. They are displayed by the GUI but are otherwise
 unused. An implementation may simply return an empty range.
 
+*BaseArch default: returns default-constructed range*
+
 ### WireId getBelPinWire(BelId bel, IdString pin) const
 
 Return the wire connected to the given bel pin.
@@ -187,7 +240,7 @@ Return the wire connected to the given bel pin.
 
 Return the type (input/output/inout) of the given bel pin.
 
-### const\_range\<IdString\> getBelPins(BelId bel) const
+### BelPinsRangeT getBelPins(BelId bel) const
 
 Return a list of all pins on that bel.
 
@@ -208,15 +261,21 @@ Get the type of a wire. The wire type is purely informal and
 isn't used by any of the core algorithms. Implementations may
 simply return `IdString()`.
 
-### const\_range\<std\:\:pair\<IdString, std::string\>\> getWireAttrs(WireId wire) const
+*BaseArch default: returns empty IdString*
+
+### WireAttrsRangeT getWireAttrs(WireId wire) const
 
 Return the attributes for that wire. Wire attributes are only informal. They are displayed by the GUI but are otherwise
 unused. An implementation may simply return an empty range.
 
+*BaseArch default: returns default-constructed range*
+
 ### uint32\_t getWireChecksum(WireId wire) const
 
 Return a (preferably unique) number that represents this wire. This is used in design state checksum calculations.
 
+*BaseArch default: returns `std::hash` of `WireId` cast to `uint32_t`*
+
 ### void bindWire(WireId wire, NetInfo \*net, PlaceStrength strength)
 
 Bind a wire to a net. This method must be used when binding a wire that is driven by a bel pin. Use `binPip()`
@@ -224,39 +283,51 @@ when binding a wire that is driven by a pip.
 
 This method must also update `net->wires`.
 
+*BaseArch default: binds using `base_wire2net`*
+
 ### void unbindWire(WireId wire)
 
 Unbind a wire. For wires that are driven by a pip, this will also unbind the driving pip.
 
 This method must also update `NetInfo::wires`.
 
+*BaseArch default: unbinds using `base_wire2net`*
+
 ### bool checkWireAvail(WireId wire) const
 
 Return true if the wire is available, i.e. can be bound to a net.
 
+*BaseArch default: returns `getBoundWireNet(wire) == nullptr`*
+
 ### NetInfo \*getBoundWireNet(WireId wire) const
 
 Return the net a wire is bound to.
 
+*BaseArch default: returns entry in `base_wire2net`*
+
 ### WireId getConflictingWireWire(WireId wire) const
 
 If this returns a non-WireId(), then unbinding that wire
 will make the given wire available.
 
+*BaseArch default: returns `wire`*
+
 ### NetInfo \*getConflictingWireNet(WireId wire) const
 
 If this returns a non-nullptr, then unbinding that entire net
 will make the given wire available.
 
+*BaseArch default: returns `getBoundWireNet(wire)`*
+
 ### DelayInfo getWireDelay(WireId wire) const
 
 Get the delay for a wire.
 
-### const\_range\<WireId\> getWires() const
+### AllWiresRangeT getWires() const
 
 Get a list of all wires on the device.
 
-### const\_range\<BelPin\> getWireBelPins(WireId wire) const
+### WireBelPinRangeT getWireBelPins(WireId wire) const
 
 Get a list of all bel pins attached to a given wire.
 
@@ -283,11 +354,15 @@ Get the name for a pip. (Pip names must be unique.)
 Get the type of a pip. Pip types are purely informal and
 implementations may simply return `IdString()`.
 
-### const\_range\<std\:\:pair\<IdString, std::string\>\> getPipAttrs(PipId pip) const
+*BaseArch default: returns empty IdString*
+
+### PipAttrsRangeT getPipAttrs(PipId pip) const
 
 Return the attributes for that pip. Pip attributes are only informal. They are displayed by the GUI but are otherwise
 unused. An implementation may simply return an empty range.
 
+*BaseArch default: returns default-constructed range*
+
 ### Loc getPipLocation(PipId pip) const
 
 Get the X/Y/Z location of a given pip. Pip locations do not need to be unique, and in most cases they aren't. So
@@ -297,18 +372,24 @@ for pips a X/Y/Z location refers to a group of pips, not an individual pip.
 
 Return a (preferably unique) number that represents this pip. This is used in design state checksum calculations.
 
+*BaseArch default: returns `std::hash` of `WireId` cast to `uint32_t`*
+
 ### void bindPip(PipId pip, NetInfo \*net, PlaceStrength strength)
 
 Bid a pip to a net. This also bind the destination wire of that pip.
 
 This method must also update `net->wires`.
 
+*BaseArch default: binds using `base_pip2net` and `base_wire2net`*
+
 ### void unbindPip(PipId pip)
 
 Unbind a pip and the wire driven by that pip.
 
 This method must also update `NetInfo::wires`.
 
+*BaseArch default: unbinds using `base_pip2net` and `base_wire2net`*
+
 ### bool checkPipAvail(PipId pip) const
 
 Returns true if the given pip is available to be bound to a net.
@@ -317,21 +398,29 @@ Users must also check if the pip destination wire is available
 with `checkWireAvail(getPipDstWire(pip))` before binding the
 pip to a net.
 
+*BaseArch default: returns `getBoundPipNet(pip) == nullptr`*
+
 ### NetInfo \*getBoundPipNet(PipId pip) const
 
 Return the net this pip is bound to.
 
+*BaseArch default: returns entry in `base_pip2net`*
+
 ### WireId getConflictingPipWire(PipId pip) const
 
 If this returns a non-WireId(), then unbinding that wire
 will make the given pip available.
 
+*BaseArch default: returns empty `WireId()`*
+
 ### NetInfo \*getConflictingPipNet(PipId pip) const
 
 If this returns a non-nullptr, then unbinding that entire net
 will make the given pip available.
 
-### const\_range\<PipId\> getPips() const
+*BaseArch default: returns empty `getBoundPipNet(pip)`*
+
+### AllPipsRangeT getPips() const
 
 Return a list of all pips on the device.
 
@@ -350,11 +439,11 @@ anti-parallel pips.
 
 Get the delay for a pip.
 
-### const\_range\<PipId\> getPipsDownhill(WireId wire) const
+### DownhillPipRangeT getPipsDownhill(WireId wire) const
 
 Get all pips downhill of a wire, i.e. pips that use this wire as source wire.
 
-### const\_range\<PipId\> getPipsUphill(WireId wire) const
+### DownhillPipRangeT getPipsUphill(WireId wire) const
 
 Get all pips uphill of a wire, i.e. pips that use this wire as destination wire.
 
@@ -365,30 +454,44 @@ Group Methods
 
 Lookup a group by its name, which is a list of IdStrings joined by `getNameDelimiter()`.
 
+*BaseArch default: returns `GroupId()`*
+
 ### IdStringList getGroupName(GroupId group) const
 
 Get the name for a group. (Group names must be unique.)
 
-### const\_range\<GroupId\> getGroups() const
+*BaseArch default: returns `IdStringList()`*
+
+### AllGroupsRangeT getGroups() const
 
 Get a list of all groups on the device.
 
-### const\_range\<BelId\> getGroupBels(GroupId group) const
+*BaseArch default: returns default-constructed range*
+
+### GroupBelsRangeT getGroupBels(GroupId group) const
 
 Get a list of all bels within a group.
 
-### const\_range\<WireId\> getGroupWires(GroupId group) const
+*BaseArch default: asserts false as unreachable due to there being no groups*
+
+### GroupWiresRangeT getGroupWires(GroupId group) const
 
 Get a list of all wires within a group.
 
-### const\_range\<PipId\> getGroupPips(GroupId group) const
+*BaseArch default: asserts false as unreachable due to there being no groups*
+
+### GroupPipsRangeT getGroupPips(GroupId group) const
 
 Get a list of all pips within a group.
 
-### const\_range\<GroupId\> getGroupGroups(GroupId group) const
+*BaseArch default: asserts false as unreachable due to there being no groups*
+
+### GroupGroupsRangeT getGroupGroups(GroupId group) const
 
 Get a list of all groups within a group.
 
+*BaseArch default: asserts false as unreachable due to there being no groups*
+
 Delay Methods
 -------------
 
@@ -437,6 +540,8 @@ Convert a `delay_t` to an integer for checksum calculations.
 
 Overwrite or modify (in-place) the timing budget for a given arc. Returns a bool to indicate whether this was done.
 
+*BaseArch default: returns false*
+
 Flow Methods
 ------------
 
@@ -455,29 +560,39 @@ run the router.
 Graphics Methods
 ----------------
 
-### const\_range\<GraphicElement\> getDecalGraphics(DecalId decal) const
+###DecalGfxRangeT getDecalGraphics(DecalId decal) const
 
 Return the graphic elements that make up a decal.
 
 The same decal must always produce the same list. If the graphics for
 a design element changes, that element must return another decal.
 
+*BaseArch default: asserts false as unreachable due to there being no decals*
+
 ### DecalXY getBelDecal(BelId bel) const
 
 Return the decal and X/Y position for the graphics representing a bel.
 
+*BaseArch default: returns `DecalXY()`*
+
 ### DecalXY getWireDecal(WireId wire) const
 
 Return the decal and X/Y position for the graphics representing a wire.
 
+*BaseArch default: returns `DecalXY()`*
+
 ### DecalXY getPipDecal(PipId pip) const
 
 Return the decal and X/Y position for the graphics representing a pip.
 
+*BaseArch default: returns `DecalXY()`*
+
 ### DecalXY getGroupDecal(GroupId group) const
 
 Return the decal and X/Y position for the graphics representing a group.
 
+*BaseArch default: returns `DecalXY()`*
+
 Cell Delay Methods
 ------------------
 
@@ -486,18 +601,24 @@ Cell Delay Methods
 Returns the delay for the specified path through a cell in the `&delay` argument. The method returns
 false if there is no timing relationship from `fromPort` to `toPort`.
 
+*BaseArch default: returns false*
+
 ### TimingPortClass getPortTimingClass(const CellInfo \*cell, IdString port, int &clockInfoCount) const
 
 Return the _timing port class_ of a port. This can be a register or combinational input or output; clock input or
 output; general startpoint or endpoint; or a port ignored for timing purposes. For register ports, clockInfoCount is set
 to the number of associated _clock edges_ that can be queried by getPortClockingInfo.
 
+*BaseArch default: returns `TMG_IGNORE`*
+
 ### TimingClockingInfo getPortClockingInfo(const CellInfo \*cell, IdString port, int index) const
 
 Return the _clocking info_ (including port name of clock, clock polarity and setup/hold/clock-to-out times) of a
 port. Where ports have more than one clock edge associated with them (such as DDR outputs), `index` can be used to obtain
 information for all edges. `index` must be in [0, clockInfoCount), behaviour is undefined otherwise.
 
+*BaseArch default: asserts false as unreachable*
+
 Bel Buckets Methods
 -------------------
 
@@ -521,30 +642,42 @@ Strict legality step will enforce those differences, along with additional
 local constraints.  `isValidBelForCell`, `isValidBelForCellType`, and
 `isBelLocationValid` are used to enforce strict legality checks.
 
-### const\_range\<BelBucketId\> getBelBuckets() const
+### BelBucketRangeT getBelBuckets() const
 
 Return a list of all bel buckets on the device.
 
+*BaseArch default: the list of buckets created by calling `init_bel_buckets()`, based on calls to `getBelBucketForBel` for all bels*
+
 ### IdString getBelBucketName(BelBucketId bucket) const
 
 Return the name of this bel bucket.
 
+*BaseArch default: `bucket`, if `BelBucketId` is a typedef of `IdString`*
+
 ### BelBucketId getBelBucketByName(IdString bucket\_name) const
 
 Return the BelBucketId for the specified bucket name.
 
+*BaseArch default: `bucket_name`, if `BelBucketId` is a typedef of `IdString`*
+
 ### BelBucketId getBelBucketForBel(BelId bel) const
 
 Returns the bucket for a particular bel.
 
+*BaseArch default: `getBelBucketForCellType(getCellType(bel))`*
+
 ### BelBucketId getBelBucketForCell(IdString cell\_type) const
 
 Returns the bel bucket for a particular cell type.
 
-### const\_range\<BelId\> getBelsInBucket(BelBucketId bucket) const
+*BaseArch default: `getBelBucketByName(cell_type)`*
+
+### BucketBelRangeT getBelsInBucket(BelBucketId bucket) const
 
 Return the list of bels within a bucket.
 
+*BaseArch default: the list of bels in the bucket created by calling `init_bel_buckets()`*
+
 Placer Methods
 --------------
 
@@ -554,17 +687,23 @@ Returns true if the given cell can be bound to the given bel.  This check
 should be fast, compared with isValidBelForCell.  This check should always
 return the same value regardless if other cells are placed within the fabric.
 
+*BaseArch default: returns `cell_type == getBelType(bel)`*
+
 ### bool isValidBelForCell(CellInfo \*cell, BelId bel) const
 
 Returns true if the given cell can be bound to the given bel, considering
 other bound resources. For example, this can be used if there is only
 a certain number of different clock signals allowed for a group of bels.
 
+*BaseArch default: returns true*
+
 ### bool isBelLocationValid(BelId bel) const
 
 Returns true if a bell in the current configuration is valid, i.e. if
 `isValidBelForCell()` would return true for the current mapping.
 
+*BaseArch default: returns true*
+
 ### static const std::string defaultPlacer
 
 Name of the default placement algorithm for the architecture, if