Each architecture must implement the following types and APIs. Architectures can either inherit from `ArchAPI`, which is a pure virtual description of the architecture API; or `BaseArch` 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`, `std::vector`, 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 | |`BelPinsRangeT` | `IdString` | |`CellBelPinRangeT` | `IdString` | |`AllWiresRangeT` | `WireId` | |`DownhillPipRangeT` | `PipId` | |`UphillPipRangeT` | `PipId` | |`WireBelPinRangeT` | `BelPin` | |`AllPipsRangeT` | `PipId` | |`PipAttrsRangeT` | std::pair | |`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. Where a default function implementation is provided, `BaseArchRanges` (which `ArchRanges` can inherit from) will set the range type appropriately. 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. ### BelId A type representing a bel name. `BelId()` must construct a unique null-value. Must provide `==`, `!=`, and `<` operators and a `unsigned int hash() const` member function. ### WireId A type representing a wire name. `WireId()` must construct a unique null-value. Must provide `==`, `!=`, and `<` operators and a `unsigned int hash() const` member function. ### PipId A type representing a pip name. `PipId()` must construct a unique null-value. Must provide `==`, `!=`, and `<` operators and a `unsigned int hash() const` member function. ### BelBucketId A type representing a bel bucket. `BelBucketId()` must construct a unique null-value. Must provide `==`, `!=`, and `<` operators and a `unsigned int hash() const` member function. ### GroupId A type representing a group name. `GroupId()` must construct a unique null-value. Must provide `==` and `!=` operators and a `unsigned int hash() const` member function. ### DecalId A type representing a reference to a graphical decal. `DecalId()` must construct a unique null-value. Must provide `==` and `!=` operators and a `unsigned int hash() const` member function. ### ClusterId A type representing a reference to a constrained c

/*
 *  nextpnr -- Next Generation Place and Route
 *
 *  Copyright (C) 2018  gatecat <gatecat@ds0.me>
 *
 *  Permission to use, copy, modify, and/or distribute this software for any
 *  purpose with or without fee is hereby granted, provided that the above
 *  copyright notice and this permission notice appear in all copies.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
 *  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
 *  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 *  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 *  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 *  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 *  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 *
 */

#ifndef BITSTREAM_H
#define BITSTREAM_H

#include "nextpnr.h"

NEXTPNR_NAMESPACE_BEGIN

void write_bitstream(Context *ctx, std::string base_config_file = "", std::string text_config_file = "");

NEXTPNR_NAMESPACE_END

#endif // BITSTREAM_H

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)`* ### DelayQuad getWireDelay(WireId wire) const Get the delay for a wire. ### AllWiresRangeT getWires() const Get a list of all wires on the device. ### WireBelPinRangeT getWireBelPins(WireId wire) const Get a list of all bel pins attached to a given wire. ### ArcBounds getRouteBoundingBox(WireId src, WireId dst) const Get the bounding box required to route an arc, assuming an uncongested chip. There may be significant performance impacts if routing regularly exceeds these bounds by more than a small margin; so an over-estimate of the bounds is almost always better than an under-estimate. Pip Methods ----------- ### PipId getPipByName(IdStringList name) const Lookup a pip by its name, which is a list of IdStrings joined by `getNameDelimiter()`. ### IdStringList getPipName(PipId pip) const Get the name for a pip. (Pip names must be unique.) ### IdString getPipType(PipId pip) const Get the type of a pip. Pip types are purely informal and implementations may simply return `IdString()`. *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 for pips a X/Y/Z location refers to a group of pips, not an individual pip. ### uint32\_t getPipChecksum(PipId pip) const Return a (preferably unique) number that represents this pip. This is used in design state checksum calculations. *BaseArch default: returns `pip.hash()`* ### 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. 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`* ### bool checkPipAvailForNet(PipId pip, NetInfo *net) const Returns true if the given pip is available to be bound to a net, or if the pip is already bound to that net. *BaseArch default: returns `getBoundPipNet(pip) == nullptr || getBoundPipNet(pip) == net`* ### 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. *BaseArch default: returns empty `getBoundPipNet(pip)`* ### AllPipsRangeT 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 modeled using two anti-parallel pips. ### DelayQuad getPipDelay(PipId pip) const Get the delay for a pip. ### DownhillPipRangeT getPipsDownhill(WireId wire) const Get all pips downhill of a wire, i.e. pips that use this wire as source wire. ### DownhillPipRangeT getPipsUphill(WireId wire) const Get all pips uphill of a wire, i.e. pips that use this wire as destination wire. Group Methods ------------- ### GroupId getGroupByName(IdStringList name) const 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.) *BaseArch default: returns `IdStringList()`* ### AllGroupsRangeT getGroups() const Get a list of all groups on the device. *BaseArch default: returns default-constructed range* ### GroupBelsRangeT getGroupBels(GroupId group) const Get a list of all bels within a group. *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. *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. *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 ------------- ### delay\_t estimateDelay(WireId src, WireId dst) const Return a rough estimate for the total `maxDelay()` delay from the given src wire to the given dst wire. 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 acceptable to return a slightly too high result and it is considered less acceptable to return a too low result (thus "low upper bound"). ### delay\_t predictDelay(const NetInfo \*net\_info, const PortRef &sink) const Return a reasonably good estimate for the total `maxDelay()` delay for the given arc. This should return a low upper bound for the fastest route for that arc. ### 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. ### delay_t getDelayFromNS(float v) const Convert a real-world delay in nanoseconds to a `delay_t`. ### uint32\_t getDelayChecksum(delay\_t v) const Convert a `delay_t` to an integer for checksum calculations. ### bool getBudgetOverride(const NetInfo \*net\_info, const PortRef &sink, delay\_t &budget) const 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 ------------ ### bool pack() Run the packer. ### bool place() Run the placer. ### bool route() run the router. Graphics Methods ---------------- ###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: returns default-constructed range* ### 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 ------------------ ### bool getCellDelay(const CellInfo \*cell, IdString fromPort, IdString toPort, DelayQuad &delay) const 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 ------------------- Bel buckets are subsets of BelIds and cell types used by analytic placer to seperate types of bels during placement. The buckets should form an exact cover over all BelIds and cell types. Each bel bucket should be BelIds and cell types that are roughly interchangable during placement. Typical buckets are: - All LUT bels - All FF bels - All multipliers bels - All block RAM bels - etc. The bel buckets will be used during analytic placement for spreading prior to strict legality enforcement. It is not required that all bels within a bucket are strictly equivelant. Strict legality step will enforce those differences, along with additional local constraints. `isValidBelForCellType`, and `isBelLocationValid` are used to enforce strict legality checks. ### 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(getBelType(bel))`* ### BelBucketId getBelBucketForCellType(IdString cell\_type) const Returns the bel bucket for a particular cell type. *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 -------------- ### bool isValidBelForCellType(IdString cell\_type, BelId bel) const Returns true if the given cell can be bound to the given bel. This check should be fast, compared with isBelLocationValid. 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 isBelLocationValid(BelId bel) const Returns true if a bel in the current configuration is legal (for example, a flipflop's clock signal is correctly shared with all bels in a slice.) *BaseArch default: returns true* ### static const std::string defaultPlacer Name of the default placement algorithm for the architecture, if `--placer` isn't specified on the command line. ### static const std::vector\ availablePlacers Name of available placer algorithms for the architecture, used to provide help for and validate `--placer`. ### static const std::string defaultRouter Name of the default router algorithm for the architecture, if `--router` isn't specified on the command line. ### static const std::vector\ availableRouters 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(const 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(const 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\\> &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.