caiyu/nextpnr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve archapi doc

Browse Source 
Signed-off-by: Clifford Wolf <clifford@clifford.at>
This commit is contained in:
Clifford Wolf 2018-08-01 11:30:00 +02:00
parent 29dd98420b
commit 0038fe268e
2 changed files with 264 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

339
docs/archapi.md
View File

@ -9,7 +9,7 @@ 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. With the exception of `ArchNetInfo` and `ArchCellInfo`, the following types should be "lightweight" enough so that passing them by value is sensible.
### delay_t ### delay\_t
A scalar type that is used to represent delays. May be an integer or float type. A scalar type that is used to represent delays. May be an integer or float type.
@ -127,7 +127,7 @@ Get the X/Y/Z location of a given bel.
Lookup a bel by its X/Y/Z location. Lookup a bel by its X/Y/Z location.
### const_range\<BelId\> getBelsByTile(int x, int y) const ### const\_range\<BelId\> getBelsByTile(int x, int y) const
Return a list of all bels at the give X/Y location. Return a list of all bels at the give X/Y location.
@ -135,18 +135,22 @@ 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. 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 ### uint32\_t getBelChecksum(BelId bel) const
Return a checksum for the state of a bel. (Used to calculate the design checksum.) Return a (preferably unique) number that represents this bel. This is used in design state checksum calculations.
### void bindBel(BelId bel, IdString cell, PlaceStrength strength) ### void bindBel(BelId bel, IdString cell, PlaceStrength strength)
Bind a given bel to a given cell with the given strength. Bind a given bel to a given cell with the given strength.
This method must also update `CellInfo::bel` and `CellInfo::belStrength`.
### void unbindBel(BelId bel) ### void unbindBel(BelId bel)
Unbind a bel. Unbind a bel.
This method must also update `CellInfo::bel` and `CellInfo::belStrength`.
### bool checkBelAvail(BelId bel) const ### 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. 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.
@ -159,7 +163,7 @@ Return the cell the given bel is bound to, or `IdString()` if the bel is not bou
If the bel is unavailable, and unbinding a single cell would make it available, then this method must return the name of that cell. 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 ### const\_range\<BelId\> getBels() const
Return a list of all bels on the device. Return a list of all bels on the device.
@ -175,108 +179,291 @@ Return the wire connected to the given bel pin.
Return the type (input/output/inout) of the given bel pin. Return the type (input/output/inout) of the given bel pin.
### const_range\<PortPin\> getBelPins(BelId bel) const ### const\_range\<PortPin\> getBelPins(BelId bel) const
Return a list of all pins on that bel. Return a list of all pins on that bel.
Wire Methods Wire Methods
------------ ------------
``` ### WireId getWireByName(IdString name) const
WireId getWireByName(IdString name) const
IdString getWireName(WireId wire) const Lookup a wire by its name.
IdString getWireType(WireId wire) const
uint32_t getWireChecksum(WireId wire) const ### IdString getWireName(WireId wire) const
void bindWire(WireId wire, IdString net, PlaceStrength strength)
void unbindWire(WireId wire) Get the name for a wire. (Wire names must be unique.)
bool checkWireAvail(WireId wire) const
IdString getBoundWireNet(WireId wire) const ### IdString getWireType(WireId wire) const
IdString getConflictingWireNet(WireId wire) const
DelayInfo getWireDelay(WireId wire) const Get the type of a wire. The wire type is purely informal and
const_range<WireId> getWires() const isn't used by any of the core algorithms. Implementations may
const_range<BelPin> getWireBelPins(WireId wire) const simply return `IdString()`.
```
### uint32\_t getWireChecksum(WireId wire) const
Return a (preferably unique) number that represents this wire. This is used in design state checksum calculations.
### void bindWire(WireId wire, IdString 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()`
when binding a wire that is driven by a pip.
This method must also update `NetInfo::wires`.
### 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`.
### bool checkWireAvail(WireId wire) const
Return true if the wire is available, i.e. can be bound to a net.
### IdString getBoundWireNet(WireId wire) const
Return the net a wire is bound to.
### IdString getConflictingWireNet(WireId wire) const
If this returns a non-empty IdString, then unbinding that net
will make the given wire available.
This returns an empty IdString if the wire is already available,
or if there is no single net that can be unbound to make this
wire available.
### DelayInfo getWireDelay(WireId wire) const
Get the delay for a wire.
### const\_range\<WireId\> getWires() const
Get a list of all wires on the device.
### const\_range\<BelPin\> getWireBelPins(WireId wire) const
Get a list of all bel pins attached to a given wire.
Pip Methods Pip Methods
----------- -----------
``` ### PipId getPipByName(IdString name) const
PipId getPipByName(IdString name) const
IdString getPipName(PipId pip) const Lookup a pip by its name.
IdString getPipType(PipId pip) const
uint32_t getPipChecksum(PipId pip) const ### IdString getPipName(PipId pip) const
void bindPip(PipId pip, IdString net, PlaceStrength strength)
void unbindPip(PipId pip) Get the name for a pip. (Pip names must be unique.)
bool checkPipAvail(PipId pip) const
IdString getBoundPipNet(PipId pip) const ### IdString getPipType(PipId pip) const
IdString getConflictingPipNet(PipId pip) const
const_range<PipId> getPips() const Get the type of a pip. Pip types are purely informal and
WireId getPipSrcWire(PipId pip) const implementations may simply return `IdString()`.
WireId getPipDstWire(PipId pip) const
DelayInfo getPipDelay(PipId pip) const ### uint32\_t getPipChecksum(PipId pip) const
const_range<PipId> getPipsDownhill(WireId wire) const
const_range<PipId> getPipsUphill(WireId wire) const Return a (preferably unique) number that represents this pip. This is used in design state checksum calculations.
const_range<PipId> getWireAliases(WireId wire) const
``` ### void bindPip(PipId pip, IdString net, PlaceStrength strength)
Bid a pip to a net. This also bind the destination wire of that pip.
This method must also update `NetInfo::wires`.
### void unbindPip(PipId pip)
Unbind a pip and the wire driven by that pip.
This method must also update `NetInfo::wires`.
### bool checkPipAvail(PipId pip) const
Returns true if the given pip is available to be bound to a net.
### IdString getBoundPipNet(PipId pip) const
Return the net this pip is bound to.
### IdString getConflictingPipNet(PipId pip) const
Return the net that needs to be unbound in order to make this
pip available.
This does not need to (but may) return the conflicting wire if the conflict is
limited to the conflicting wire being bound to the destination wire for this
pip.
### const\_range\<PipId\> getPips() const
Return a list of all pips on the device.
### WireId getPipSrcWire(PipId pip) const
Get the source wire for a pip.
### WireId getPipDstWire(PipId pip) const
Get the destination wire for a pip.
Bi-directional switches (transfer gates) are modelled using two
antiparallel pips.
### DelayInfo getPipDelay(PipId pip) const
Get the delay for a pip.
### const\_range\<PipId\> 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
Get all pips uphill of a wire, i.e. pips that use this wire as destination wire.
### const\_range\<PipId\> getWireAliases(WireId wire) const
Get all alias pips downhill of a wire.
There is no api for getting the alias pips uphill of a wire.
Alias pips come in antiparallel pairs if a signal can be injected on either
side of the alias pip.
Group Methods Group Methods
------------- -------------
``` ### GroupId getGroupByName(IdString name) const
GroupId getGroupByName(IdString name) const
IdString getGroupName(GroupId group) const Lookup a group by its name.
const_range<GroupId> getGroups() const
const_range<BelId> getGroupBels(GroupId group) const ### IdString getGroupName(GroupId group) const
const_range<WireId> getGroupWires(GroupId group) const
const_range<PipId> getGroupPips(GroupId group) const Get the name for a group. (Group names must be unique.)
const_range<GroupId> getGroupGroups(GroupId group) const
``` ### const\_range\<GroupId\> getGroups() const
Get a list of all groups on the device.
### const\_range\<BelId\> getGroupBels(GroupId group) const
Get a list of all bels within a group.
### const\_range\<WireId\> getGroupWires(GroupId group) const
Get a list of all wires within a group.
### const\_range\<PipId\> getGroupPips(GroupId group) const
Get a list of all pips within a group.
### const\_range\<GroupId\> getGroupGroups(GroupId group) const
Get a list of all groups within a group.
Delay Methods Delay Methods
------------- -------------
``` ### delay\_t estimateDelay(WireId src, WireId dst) const
delay_t estimateDelay(WireId src, WireId dst) const
delay_t getDelayEpsilon() const Return an estimate for the total `maxDelay()` delay from the given src wire to
delay_t getRipupDelayPenalty() const the given dst wire.
float getDelayNS(delay_t v) const
uint32_t getDelayChecksum(delay_t v) const This should return a low upper bound for the fastest route from `src` to `dst`.
```
Or in other words it should assume an otherwise unused chip (thus "fastest route").
But it only produces an estimate for that fastest route, not an exact
result, and for that estimate it is considered more accaptable to return a
slightly too high result and it is considered less accaptable to return a
too low result (thus "low upper bound").
### delay\_t getDelayEpsilon() const
Return a small delay value that can be used as small epsilon during routing.
The router will for example not re-calculate cached routing data if faster routes
are found when the difference is smaller than this value.
### delay\_t getRipupDelayPenalty() const
The base penality when calculating delay penalty for ripping up routed nets. The
actual penalty used is a multiple of this value (i.e. a weighted version of this value).
### float getDelayNS(delay\_t v) const
Convert an `delay_t` to an actual real-world delay in nanoseconds.
### uint32\_t getDelayChecksum(delay\_t v) const
Convert a `delay_t` to an integer for checksum calculations.
Flow Methods Flow Methods
------------ ------------
``` ### bool pack()
bool pack()
bool place() Run the packer.
bool route()
``` ### bool place()
Run the placer.
### bool route()
run the router.
Graphics Methods Graphics Methods
---------------- ----------------
``` ### const\_range\<GraphicElement\> getDecalGraphics(DecalId decal) const
const_range<GraphicElement> getDecalGraphics(DecalId decal) const
DecalXY getFrameDecal() const Return the graphic elements that make up a decal.
DecalXY getBelDecal(BelId bel) const
DecalXY getWireDecal(WireId wire) const The same decal must always produce the same list. If the graphics for
DecalXY getPipDecal(PipId pip) const a design element changes, that element must return another decal.
DecalXY getGroupDecal(GroupId group) const
``` ### DecalXY getBelDecal(BelId bel) const
Return the decal and X/Y position for the graphics representing a bel.
### DecalXY getWireDecal(WireId wire) const
Return the decal and X/Y position for the graphics representing a wire.
### DecalXY getPipDecal(PipId pip) const
Return the decal and X/Y position for the graphics representing a pip.
### DecalXY getGroupDecal(GroupId group) const
Return the decal and X/Y position for the graphics representing a group.
Cell Delay Methods Cell Delay Methods
------------------ ------------------
``` ### bool getCellDelay(const CellInfo \*cell, IdString fromPort, IdString toPort, DelayInfo &delay) const
bool getCellDelay(const CellInfo *cell, IdString fromPort, IdString toPort, DelayInfo &delay) const
IdString getPortClock(const CellInfo *cell, IdString port) const Returns the delay for the specified path through a cell in the `&delay` argument. The method returns
bool isClockPort(const CellInfo *cell, IdString port) const false if there is no timing relationship from `fromPort` to `toPort`.
```
### IdString getPortClock(const CellInfo \*cell, IdString port) const
Returns the clock input port for the specified output port.
### bool isClockPort(const CellInfo \*cell, IdString port) const
Returns true if the specified port is a clock input.
Placer Methods Placer Methods
-------------- --------------
``` ### bool isValidBelForCell(CellInfo \*cell, BelId bel) const
bool isValidBelForCell(CellInfo *cell, BelId bel) const
bool isBelLocationValid(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.
### 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.

1
docs/faq.md
View File

@ -22,6 +22,7 @@ For nextpnr we are using the following terminology.
- **Pip**: Programmable Interconnect Point, a configurable connection in one direction between two wires - **Pip**: Programmable Interconnect Point, a configurable connection in one direction between two wires
- **Wire**: a fixed physical connection inside the FPGA between Pips and/or Bel pins. - **Wire**: a fixed physical connection inside the FPGA between Pips and/or Bel pins.
- **Alias**: a special automatic-on Pip to represent a permanent connection between two wires - **Alias**: a special automatic-on Pip to represent a permanent connection between two wires
- **Group**: a collection of bels, pips, wires, and/or other groups
### Flow Terminology ### Flow Terminology