From 72244066bb0e1e400949412c8b0ee8df98725dbd Mon Sep 17 00:00:00 2001 From: David Shah Date: Sun, 29 Sep 2019 15:22:56 +0200 Subject: docs: More netlist documentation Signed-off-by: David Shah --- docs/netlist.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/docs/netlist.md b/docs/netlist.md index 09bf53d0..0f9a8969 100644 --- a/docs/netlist.md +++ b/docs/netlist.md @@ -40,3 +40,34 @@ Other structures used by these basic structures include: - Each entry in `wires` maps from *sink* wire in the routing tree to its driving pip, and the binding strength of that pip (e.g. how freely the router may rip up the pip) - Manipulation of this structure is done automatically by `Arch::bindWire`, `Arch::unbindWire`, `Arch::bindPip` and `Arch::unbindPip`; which should almost always be used in lieu of manual manipulation - `attrs` stores metadata about the wire (which may come from the JSON or be added by passes) + - `clkconstr` contains the period constraint if the wire is a constrained clock; or is empty otherwise + - `region` is a reference to a `Region` if the net is constrained to a device region or `nullptr` otherwise (_N.B. not supported by the current router_). + +## BaseCtx/Context + +Relevant fields from a netlist point of view are: + - `cells` is a map from cell name to a `unique_ptr` containing cell data + - `nets` is a map from net name to a `unique_ptr` containing net data + - `net_aliases` maps every alias for a net to its canonical name (i.e. index into `nets`) - net aliases often occur when a net has a name both inside a submodule and higher level module + - `ports` is a list of top level ports, primarily used during JSON export (e.g. to produce a useful post-PnR simulation model) + +Context also has a method `check()` that ensures all of the contracts met above are satisfied. It is strongly suggested to run this after any pass that may modify the netlist. + +## Performance Improvements + +Two features are provided to enable performance improvements in some algorithms, generally by reducing the number of `unordered_map` accesses. + +The first is `udata`. This is a field of both nets and cells that can be used to give an index into algorithm-specific structures, such as a flat `vector` of cells. Placers and routers may use this for any purpose, but it should not be used to exchange data between passes. + +The second is `ArchCellInfo` and `ArchNetInfo`. These are provided by architectures and used as base classes for `CellInfo` and `NetInfo` respectively. They allow architectures to tag information that is needed frequently - for example the clock polarity and clock net for a flipflop are needed for placement validity checking. They should only be used inside arch-specific code, and are lost when netlists are saved/loaded thus must not be used as primary storage - usually these should mirror attributes/parameters. `assignArchInfo` should set these up accordingly. + +## Helper Functions - Context + +`Context` and its subclass `BaseCtx` provides several helper functions that are often needed inside CAD algorithms. + + - `nameOfBel`, `nameOfWire`, and `nameOfPip` gets the name of an identified object as a C string, often used in conjunction with the logging functions + - `nameOf` is similar to above but for netlist objects that have a `name` field (e.g. cells, nets, etc) + - `getNetinfoSourceWire` gets the physical wire `WireId` associated with the source of a net + - `getNetinfoSinkWire` gets the physical wire `WireId` associated with a given sink (specified by `PortRef`) + - `getNetinfoRouteDelay` gets the routing delay - actual if the net is fully routed, estimated otherwise - between the source and a given sink of a net + - `getNetByAlias` returns the pointer to a net given any of its aliases - this should be used in preference to a direct lookup in `nets` whenever a net name is provided by the user \ No newline at end of file -- cgit v1.2.3