arch_api: Outline of new cluster API

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

common/arch_api.h

@@ -139,6 +139,13 @@ template <typename R> struct ArchAPI : BaseCtx
     virtual typename R::CellTypeRangeT getCellTypes() const = 0;
     virtual typename R::BelBucketRangeT getBelBuckets() const = 0;
     virtual typename R::BucketBelRangeT getBelsInBucket(BelBucketId bucket) const = 0;
+    // Cluster methods
+    virtual CellInfo *getClusterRootCell(ClusterId cluster) const = 0;
+    virtual ArcBounds getClusterBounds(ClusterId cluster) const = 0;
+    virtual Loc getClusterOffset(ClusterId cluster, CellInfo *cell) const = 0;
+    virtual bool isClusterStrict(CellInfo *cell) const = 0;
+    virtual bool getClusterPlacement(ClusterId cluster, BelId root_bel,
+                                     std::vector<std::pair<CellInfo *, BelId>> &placement) const = 0;
     // Flow methods
     virtual bool pack() = 0;
     virtual bool place() = 0;

common/nextpnr_types.h

@@ -165,15 +165,8 @@ struct CellInfo : ArchCellInfo
     BelId bel;
     PlaceStrength belStrength = STRENGTH_NONE;
 
-    // placement constraints
+    // cell is part of a cluster if != ClusterId
-    CellInfo *constr_parent = nullptr;
+    ClusterId cluster;
-    std::vector<CellInfo *> constr_children;
-    const int UNCONSTR = INT_MIN;
-    int constr_x = UNCONSTR;   // this.x - parent.x
-    int constr_y = UNCONSTR;   // this.y - parent.y
-    int constr_z = UNCONSTR;   // this.z - parent.z
-    bool constr_abs_z = false; // parent.z := 0
-    // parent.[xyz] := 0 when (constr_parent == nullptr)
 
     Region *region = nullptr;
 

docs/archapi.md

@@ -67,6 +67,10 @@ A type representing a group name. `GroupId()` must construct a unique null-value
 
 A type representing a reference to a graphical decal. `DecalId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<DecalId>`.
 
+### ClusterId
+
+A type representing a reference to a constrained cluster of cells. `ClusterId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<ClusterId>`.
+
 ### ArchNetInfo
 
 The global `NetInfo` type derives from this one. Can be used to add arch-specific data (caches of information derived from wire attributes, bound wires and pips, and other net state). Must be declared as empty struct if unused.
@@ -720,3 +724,32 @@ Name of the default router algorithm for the architecture, if
 
 Name of available router algorithms for the architecture, used
 to provide help for and validate `--router`.
+
+Cluster Methods
+---------------
+
+### CellInfo *getClusterRootCell(ClusterId cluster) const
+
+Gets the root cell of a cluster, which is used as a datum point when placing the cluster.
+
+### ArcBounds getClusterBounds(ClusterId cluster) const
+
+Gets an approximate bounding box of the cluster. This is intended for area allocation in the placer and is permitted to occasionally give incorrect estimates, for example due to irregularities in the fabric depending on cluster placement. `getClusterPlacement` should always be used to get exact locations.
+
+### Loc getClusterOffset(CellInfo \*cell) const
+
+Gets the approximate offset of a cell within its cluster, relative to the root cell. This is intended for global placement usage and is permitted to occasionally give incorrect estimates, for example due to irregularities in the fabric depending on cluster placement. `getClusterPlacement` should always be used to get exact locations.
+
+The returned x and y coordinates, when added to the root location of the cluster, should give an approximate location where `cell` will end up placed at.
+
+### bool isClusterStrict(CellInfo *cell) const
+
+Returns `true` if the cell **must** be placed according to the cluster; for example typical carry chains, and dedicated IO routing. Returns `false` if the cell can be split from the cluster if placement desires, at the expense of a less optimal result (for example dedicated LUT-FF paths where general routing can also be used).
+
+### bool getClusterPlacement(ClusterId cluster, BelId root\_bel, std::vector\<std::pair\<CellInfo \*, BelId\>\> &placement) const
+
+Gets an exact placement of the cluster, with the root cell placed on or near `root_bel` (and always within the same tile). Returns false if no placement is viable, otherwise returns `true` and populates `placement` with a list of cells inside the cluster and bels they should be placed at.
+
+This approach of allowing architectures to define cluster placements enables easier handling of irregular fabrics than requiring strict and constant x, y and z offsets.
+
+

docs/netlist.md

@@ -23,11 +23,7 @@ Other structures used by these basic structures include:
  - `ports` is a map from port name `IdString` to `PortInfo` structures for each cell port
  - `bel` and `belStrength` contain the ID of the Bel the cell is placed onto; and placement strength of the cell; if placed. Placement/ripup should always be done by `Arch::bindBel` and `Arch::unbindBel` rather than by manipulating these fields.
  - `params` and `attrs` store parameters and attributes - from the input JSON or assigned in flows to add metadata - by mapping from parameter name `IdString` to `Property`.
- - The `constr_` fields are for relative constraints:
+ - `cluster` is used to specify that the cell is inside a placement cluster, with the details of the placement within the cluster provided by the architecture.
-    - `constr_parent` is a reference to the cell this cell is constrained with respect to; or `nullptr` if not relatively constrained. If not `nullptr`, this cell should be in the parent's `constr_children`.
-    - `constr_children` is a list of cells relatively constrained to this one. All children should have `constr_parent == this`. 
-    - `constr_x` and `constr_y` are absolute (`constr_parent == nullptr`) or relative (`constr_parent != nullptr`) tile coordinate constraints. If set to `UNCONSTR` then the cell is not constrained in this axis (defaults to `UNCONSTR`)
-    - `constr_z` is an absolute (`constr_abs_z`) or relative (`!constr_abs_z`) 'Z-axis' (index inside tile, e.g. logic cell) constraint
  - `region` is a reference to a `Region` if the cell is constrained to a placement region (e.g. for partial reconfiguration or out-of-context flows) or `nullptr` otherwise.
 
 ## NetInfo