diff options
Diffstat (limited to 'docs/archapi.md')
| -rw-r--r-- | docs/archapi.md | 282 |
1 files changed, 282 insertions, 0 deletions
diff --git a/docs/archapi.md b/docs/archapi.md new file mode 100644 index 00000000..4cd4d963 --- /dev/null +++ b/docs/archapi.md @@ -0,0 +1,282 @@ +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. + +archdefs.h +========== + +The architecture-specific `archdefs.h` must define the following types. + +With the exception of `ArchNetInfo` and `ArchCellInfo`, the following types should be "lightweight" enough so that passing them by value is sensible. + +### delay_t + +A scalar type that is used to represent delays. May be an integer or float type. + +### DelayInfo + +A struct representing the delay across a timing arc. Must provide a `+` operator for getting the combined delay of two arcs, and the following methods to access concrete timings: + +``` +delay_t minRaiseDelay() const { return delay; } +delay_t maxRaiseDelay() const { return delay; } + +delay_t minFallDelay() const { return delay; } +delay_t maxFallDelay() const { return delay; } + +delay_t minDelay() const { return delay; } +delay_t maxDelay() const { return delay; } +``` + +### BelType + +A type representing a bel type name. `BelType()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<BelType>`. + +### PortPin + +A type representing a port or pin name. `PortPin()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<PortPin>`. + +### BelId + +A type representing a bel name. `BelId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<BelId>`. + +### WireId + +A type representing a wire name. `WireId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<WireId>`. + +### PipId + +A type representing a pip name. `PipId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<PipId>`. + +### GroupId + +A type representing a group name. `GroupId()` must construct a unique null-value. Must provide `==` and `!=` operators and a specialization for `std::hash<GroupId>`. + +### DecalId + +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>`. + +### 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. + +### ArchCellInfo + +The global `CellInfo` type derives from this one. Can be used to add arch-specific data (caches of information derived from cell attributes and parameters, bound bel, and other cell state). Must be declared as empty struct if unused. + +arch.h +====== + +Each architecture must provide their own implementation of the `Arch` struct in `arch.h`. `Arch` must derive from `BaseCtx` and must provide the following methods: + +General Methods +--------------- + +### Arch(ArchArgs args) + +Constructor. ArchArgs is a architecture-specific type (usually a struct also defined in `arch.h`). + +### std::string getChipName() const + +Return a string representation of the ArchArgs that was used to construct this object. + +### IdString belTypeToId(BelType type) const + +Convert a `BelType` to an `IdString`. + +### IdString portPinToId(PortPin type) const + +Convert a `PortPin` to an `IdString`. + +### BelType belTypeFromId(IdString id) const + +Convert `IdString` to `BelType`. + +### PortPin portPinFromId(IdString id) const + +Convert `IdString` to `PortPin`. + +### int getGridDimX() const + +Get grid X dimension. All bels must have Y coordinates in the range `0 .. getGridDimX()-1` (inclusive). + +### int getGridDimY() const + +Get grid Y dimension. All bels must have Y coordinates in the range `0 .. getGridDimY()-1` (inclusive). + +### int getTileDimZ(int x, int y) const + +Get Z dimension for the specified tile. All bels with the specified X and Y coordinates must have a Z coordinate in the range `0 .. getTileDimZ(X,Y)-1` (inclusive). + +Bel Methods +----------- + +### BelId getBelByName(IdString name) const + +Lookup a bel by its name. + +### IdString getBelName(BelId bel) const + +Get the name for a bel. (Bel names must be unique.) + +### Loc getBelLocation(BelId bel) const + +Get the X/Y/Z location of a given bel. + +### BelId getBelByLocation(Loc loc) const + +Lookup a bel by its X/Y/Z location. + +### const_range\<BelId\> getBelsByTile(int x, int y) const + +Return a list of all bels at the give X/Y location. + +### bool getBelGlobalBuf(BelId bel) const + +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. + +### uint32_t getBelChecksum(BelId bel) const + +Return a checksum for the state of a bel. (Used to calculate the design checksum.) + +### void bindBel(BelId bel, IdString cell, PlaceStrength strength) + +Bind a given bel to a given cell with the given strength. + +### void unbindBel(BelId bel) + +Unbind a bel. + +### 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. + +### IdString getBoundBelCell(BelId bel) const + +Return the cell the given bel is bound to, or `IdString()` if the bel is not bound. + +### IdString getConflictingBelCell(BelId bel) const + +If the bel is unavailable, and unbinding a single cell would make it available, then this method must return the name of that cell. + +### const_range\<BelId\> getBels() const + +Return a list of all bels on the device. + +### BelType getBelType(BelId bel) const + +Return the type of a given bel. + +### WireId getBelPinWire(BelId bel, PortPin pin) const + +Return the wire connected to the given bel pin. + +### PortType getBelPinType(BelId bel, PortPin pin) const + +Return the type (input/output/inout) of the given bel pin. + +### const_range\<PortPin\> getBelPins(BelId bel) const + +Return a list of all pins on that bel. + +Wire Methods +------------ + +``` +WireId getWireByName(IdString name) const +IdString getWireName(WireId wire) const +IdString getWireType(WireId wire) const +uint32_t getWireChecksum(WireId wire) const +void bindWire(WireId wire, IdString net, PlaceStrength strength) +void unbindWire(WireId wire) +bool checkWireAvail(WireId wire) const +IdString getBoundWireNet(WireId wire) const +IdString getConflictingWireNet(WireId wire) const +DelayInfo getWireDelay(WireId wire) const +const_range<WireId> getWires() const +const_range<BelPin> getWireBelPins(WireId wire) const +``` + +Pip Methods +----------- + +``` +PipId getPipByName(IdString name) const +IdString getPipName(PipId pip) const +IdString getPipType(PipId pip) const +uint32_t getPipChecksum(PipId pip) const +void bindPip(PipId pip, IdString net, PlaceStrength strength) +void unbindPip(PipId pip) +bool checkPipAvail(PipId pip) const +IdString getBoundPipNet(PipId pip) const +IdString getConflictingPipNet(PipId pip) const +const_range<PipId> getPips() const +WireId getPipSrcWire(PipId pip) const +WireId getPipDstWire(PipId pip) const +DelayInfo getPipDelay(PipId pip) const +const_range<PipId> getPipsDownhill(WireId wire) const +const_range<PipId> getPipsUphill(WireId wire) const +const_range<PipId> getWireAliases(WireId wire) const +``` + +Group Methods +------------- + +``` +GroupId getGroupByName(IdString name) const +IdString getGroupName(GroupId group) const +const_range<GroupId> getGroups() const +const_range<BelId> getGroupBels(GroupId group) const +const_range<WireId> getGroupWires(GroupId group) const +const_range<PipId> getGroupPips(GroupId group) const +const_range<GroupId> getGroupGroups(GroupId group) const +``` + +Delay Methods +------------- + +``` +delay_t estimateDelay(WireId src, WireId dst) const +delay_t getDelayEpsilon() const +delay_t getRipupDelayPenalty() const +float getDelayNS(delay_t v) const +uint32_t getDelayChecksum(delay_t v) const +``` + +Flow Methods +------------ + +``` +bool pack() +bool place() +bool route() +``` + +Graphics Methods +---------------- + +``` +const_range<GraphicElement> getDecalGraphics(DecalId decal) const +DecalXY getFrameDecal() const +DecalXY getBelDecal(BelId bel) const +DecalXY getWireDecal(WireId wire) const +DecalXY getPipDecal(PipId pip) const +DecalXY getGroupDecal(GroupId group) const +``` + +Cell Delay Methods +------------------ + +``` +bool getCellDelay(const CellInfo *cell, IdString fromPort, IdString toPort, DelayInfo &delay) const +IdString getPortClock(const CellInfo *cell, IdString port) const +bool isClockPort(const CellInfo *cell, IdString port) const +``` + +Placer Methods +-------------- + +``` +bool isValidBelForCell(CellInfo *cell, BelId bel) const +bool isBelLocationValid(BelId bel) const +``` |