Merge remote-tracking branch 'origin/master' into mmicko/ecp5_gui

3 files changed, 34 insertions, 25 deletions

diff --git a/docs/faq.md b/docs/faq.md
index 7b358187..fe0c7231 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -132,9 +132,8 @@ Nextpnr and other tools
 
 ### Which toolchain should I use and why?
 
- * If you wish to do new **research** into FPGA architectures, place and route
-   algorithms or other similar topics, we suggest you look at using
-   [Verilog to Routing](https://verilogtorouting.org).
+ * If you wish to do new **research** into FPGA architectures, or other similar topics, we suggest you look at using
+   [Verilog to Routing](https://verilogtorouting.org). If you want to use nextpnr, you might also be able to use the [Generic Arch](generic.md).
 
  * If you are developing FPGA code in **Verilog** for a **Lattice iCE40** and
    need an open source toolchain, we suggest you use [Yosys](http://www.clifford.at/yosys/) and nextpnr.
@@ -144,14 +143,9 @@ Nextpnr and other tools
    migrating to nextpnr.
 
  * If you are developing Verilog FPGA code targeted at the Lattice ECP5 and
-   need an open source toolchain, you may consider the **extremely
-   experimental** ECP5 support in Yosys and nextpnr.
+   need an open source toolchain, there is also stable ECP5 support in Yosys and nextpnr.
 
- * If you are developing FPGA code in **VHDL** you will need to use either a
-   version of [Yosys with Verific support](https://github.com/YosysHQ/yosys/tree/master/frontends/verific) or the vendor provided tools due
-   to the lack of useful open source VHDL support in Yosys. You could also look at developing
-   one of the experimental open source VHDL frontends, such as [yavhdl](https://github.com/rqou/yavhdl)
-   or [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta), further.
+ * If you are developing FPGA code in **VHDL** you may wish to look at the [ghdlsynth-beta](https://github.com/tgingold/ghdlsynth-beta) experimental VHDL frontend for Yosys.
 
 ### Why didn't you just improve [arachne-pnr](https://github.com/cseed/arachne-pnr)?
 
@@ -162,11 +156,9 @@ that actually produced valid bitstreams.
 
 For its original purpose, it has served the community extremely well. However,
 it was never designed to support multiple different FPGA families, nor more
-complicated timing driven placement and routing used by most commercial place and route
-tools.
+complicated timing driven placement and routing used by most commercial place and route tools.
 
-It felt like extending arachne-pnr was not going to be the best path forward, so
-it was decided to build nextpnr as replacement.
+It felt like extending arachne-pnr was not going to be the best path forward, so it was decided to build nextpnr as replacement.
 
 ### arachne-pnr does X better!
 
@@ -174,7 +166,8 @@ If you have a use case which prevents you from switching to nextpnr from
 arachne, we want to hear about it! Please create an issue and we will do our best to solve the problem!
 
 We want nextpnr to be a suitable replacement for anyone who is currently a user
-of arachne-pnr.
+of arachne-pnr, and it is important to bear in mind that arachne-pnr is no
+longer in active development.
 
 ### Why are you not just contributing to [Verilog to Routing](https://verilogtorouting.org)?
 
@@ -191,8 +184,7 @@ for current FPGAs.
 
 We also believe that support for real architectures will enable interesting new
 research. nextpnr (like all place and route tools) depends heavily on
-research groups like the VtR developers to investigate and push forward FPGA placement and routing
-algorithms in new and exciting ways.
+research groups like the VtR developers to investigate and push forward FPGA placement and routing algorithms in new and exciting ways.
 
 #### What is VPR?
 
@@ -220,15 +212,14 @@ enable support for creation of bitstreams for these parts.
 the bitstream format for the Xilinx Series 7 series of FPGAs. It also includes
 tooling around bitstream generation for these parts.
 
-While nextpnr currently does **not** support these Xilinx parts, we expect it
-will soon be using Project X-Ray in a similar manner to Project Trellis.
+While upstream nextpnr currently does **not** support these Xilinx parts, we expect it might soon be using Project X-Ray in a similar manner to Project Trellis.
 
 ### What is [Project IceStorm](http://www.clifford.at/icestorm/)?
 
 [Project IceStorm](http://www.clifford.at/icestorm/) is both a project to
 document the bitstream for the Lattice iCE40 series of parts **and** a full
-flow including Yosys and arachne-pnr for converting Verilog into a bitstream for
-these parts.
+flow including Yosys and arachne-pnr for converting Verilog into a bitstream 
+for these parts.
 
 As the open source community now has support for multiple different FPGA parts,
 in the nextpnr documentation we generally use Project IceStorm to mean the database and
diff --git a/docs/generic.md b/docs/generic.md
index d6ddbfb6..a635f98c 100644
--- a/docs/generic.md
+++ b/docs/generic.md
@@ -72,7 +72,7 @@ Sets the number of input pins a LUT in the architecture has. Only affects the ge
 
 ### void setDelayScaling(double scale, double offset);
 
-Set the linear scaling vs distance and fixed offset (both values in nanoseconds) for routing delay estimates.
+Set the linear scaling vs distance and fixed offset (both values in nanoseconds) for routing delay estimates. Delay estimates that correlate to pip delays, even if they have no bearing to reality, are important for reasonable routing runtime.
 
 ### void addCellTimingClock(IdString cell, IdString port);
 
@@ -96,17 +96,19 @@ Specify clock-to-out time for a port of a cell, and set the timing class of that
 
 ## Generic Packer
 
-The generic packer combines K-input LUTs (`LUT` cells) and simple D-type flip flops (`DFF` cells) (posedge clock only, no set/reset or enable) into a `GENERIC_SLICE` cell. It also inserts `GENERIC_IOB`s onto any top level IO pins without an IO buffer.
+The generic packer combines K-input LUTs (`LUT` cells) and simple D-type flip flops (`DFF` cells) (posedge clock only, no set/reset or enable) into a `GENERIC_SLICE` cell. It also inserts `GENERIC_IOB`s onto any top level IO pins without an IO buffer. Constrained IOBs can be implemented by instantiating `GENERIC_IOB` and setting the `BEL` attribute to an IO location.
 
 Thus, the architecture should provide bels with the following ports in order to use the generic packer:
 
- - `GENERIC_SLICE` bels with `CLK` input, `I[0]` .. `I[K-1]` LUT inputs and `Q` LUT/FF output (N.B. both LUT and FF outputs are not available at the same time)
+ - `GENERIC_SLICE` bels with `CLK` input, `I[0]` .. `I[K-1]` LUT inputs, `F` LUT output and `Q` FF output (N.B. both LUT and FF outputs are not available at the same time, to represent the constraints of some FPGAs).
  - `GENERIC_IOB` bels with `I` output buffer input, `EN` output enable input, and `O` input buffer output.
 
 See [prims.v](../generic/synth/prims.v) for Verilog simulation models for all these cells.
 
 [synth_generic.tcl](../generic/synth/synth_generic.tcl) can be used with Yosys to perform synthesis to the generic `LUT` and `DFF` cells which the generic packer supports. Invoke it using `tcl synth_generic.tcl K out.json` where _K_ is the number of LUT inputs and _out.json_ the name of the JSON file to write.
 
+The generic packer in its current state is intended for experimentation and proof-of-concept tests. It is _not_ intended to make use of all FPGA features or support complex designs. In these cases a proper [Arch API](archapi.md) implementation is strongly recommended.
+
 ## Validity Checks
 
 The following constraints are enforced by the generic architecture during placement.
diff --git a/docs/netlist.md b/docs/netlist.md
index 0f9a8969..3953241e 100644
--- a/docs/netlist.md
+++ b/docs/netlist.md
@@ -19,6 +19,7 @@ Other structures used by these basic structures include:
 `CellInfo` instances have the following fields:
 
  - `name` and `type` are `IdString`s containing the instance name, and type
+ - `hierpath` is name of the hierarchical cell containing the instance, for designs with hierarchy
  - `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`.
@@ -34,6 +35,7 @@ Other structures used by these basic structures include:
 `NetInfo` instances have the following fields:
 
  - `name` is the IdString name of the net - for nets with multiple names, one name is chosen according to a set of rules by the JSON frontend
+ - `hierpath` is name of the hierarchical cell containing the instance, for designs with hierarchy
  - `driver` refers to the source of the net using `PortRef`; `driver.cell == nullptr` means that the net is undriven. Nets must have zero or one driver only. The corresponding cell port must be an output and its `PortInfo::net` must refer back to this net.
  - `users` contains a list of `PortRef` references to sink ports on the net. Nets can have zero or more sinks. Each corresponding cell port must be an input or inout; and its `PortInfo::net` must refer back to this net.
  - `wires` is a map that stores the routing tree of a net, if the net is routed.
@@ -70,4 +72,18 @@ The second is `ArchCellInfo` and `ArchNetInfo`. These are provided by architectu
  - `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
+ - `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
+
+## Hierarchy
+
+As most place and route algorithms require a flattened netlist to work with (consider - each leaf cell instance must have its own bel), the primary netlist structures are flattened. However, some tasks such as floorplanning require an understanding of hierarchy. 
+
+`HierarchicalCell` is the main data structure for storing hierarchy. This represents an instance of a hierarchical, rather than leaf cell (leaf cells are represented by a `CellInfo`).
+
+ - `name` and `type` are the instance name and cell type
+ - `parent` is the hierarchical path of the parent cell, and `fullpath` is the hierarchical path of this cell
+ - `leaf_cells`, `nets` map from a name inside the hierarchical cell to a 'global' name in the flattened netlist (i.e. one that indexes into `ctx->{cells,nets}`)
+ - `leaf_cells_by_gname`, `nets_by_gname` are the inverse of the above maps; going from `{CellInfo,NetInfo}::name` to an instance name inside the cell
+ - `hier_cells` maps instance names of sub-hierarchical (non-leaf) cells to global names (indexing into `ctx->hierarchy`)
+
+To preserve hierarchy during passes such as packing, ensure that `hierpath` is set on new cells derived from existing ones, and call `fixupHierarchy()` at the end to rebuild `HierarchicalCell` structures.