Updated documentation for FASM annotation examples

Signed-off-by: Maciej Kurc <[email protected]>

tests/fasm/README.rst

@@ -0,0 +1,12 @@
+FASM annotation support
+=======================
+
+These examples illustrate how to apply FASM annotations to various elements of the FPGA architecture description.
+
+FASM annotation of elements of FPGA architecture model is necessary for VPR to produce a list of FASM features once a design is routed. The features may be then used to generate a bitstream for a FPGA. More on FASM output support in VPR can be found in the `documentation <https://docs.verilogtorouting.org/en/latest/utils/fasm/?highlight=fasm#fpga-assembly-fasm-output-support>`_.
+
+.. toctree::
+   prefix/README.rst
+   features/no_modes/README.rst
+   features/modes/README.rst
+   params/README.rst

tests/fasm/features/modes/README.rst

@@ -0,0 +1,25 @@
+FASM features for pb_types with modes
++++++++++++++++++++++++++++++++++++++
+
+When a pb_type has multiple modes feature lists for each modes may be specified through the `(* FASM_FEATURES_<mode> *)` attribute(s). Each mode specific feature list will be joined with the common feature list provided using the `(* FASM_FEATURES *)` attribute.
+
+
+.. symbolator:: module.sim.v
+
+.. verilog-diagram:: module.sim.v
+   :type: netlistsvg
+   :module: MODULE
+
+.. no-license:: module.sim.v
+   :language: verilog
+   :caption: tests/fasm/features/modes/module.sim.v
+
+Features from the common feature list will be appended to the pb_type that contains the "mode" tag. Features from mode specific lists will be appended to pb_types that will represent the modes.
+
+.. literalinclude:: module.model.xml
+   :language: xml
+   :caption: module.model.xml
+
+.. literalinclude:: module.pb_type.xml
+   :language: xml
+   :caption: module.pb_type.xml

tests/fasm_features/modes/module.sim.v → tests/fasm/features/modes/module.sim.v

@@ -11,16 +11,17 @@
 `include "./gate/gate.sim.v"
 
 (* FASM_FEATURES="IN_USE" *)
-(* FASM_FEATURES_MODE_B="SEL_MODE_B;ENABLE_SOMETHING_B" *)
 (* FASM_FEATURES_MODE_A="SEL_MODE_A;ENABLE_SOMETHING_A" *)
+(* FASM_FEATURES_MODE_B="SEL_MODE_B;ENABLE_SOMETHING_B" *)
 (* MODES="MODE_A;MODE_B;MODE_C" *)
 module MODULE(I0, I1, O);
+
+  parameter MODE = "MODE_A";
+
   input  wire I0;
   input  wire I1;
   output wire O;
 
-  parameter MODE = "";
-
   generate if (MODE == "MODE_A") begin
     GATE gate (I1, I0, O);
   end else if (MODE == "MODE_B") begin

tests/fasm/features/no_modes/README.rst

@@ -0,0 +1,26 @@
+FASM features for pb_types
+++++++++++++++++++++++++++
+
+A VPR pb_type can be assigned with a number of fasm features that are emitted when it is used. https://docs.verilogtorouting.org/en/latest/utils/fasm/#fasm-metadata
+
+In V2X the list of those features is defined via the `(* FASM_FEATURES *)` attribute of the Verilog module definition which represents a pb_type. The list contains a set of semicolon separated fasm feature names. It is an error to specify `(* FASM_FEATURES *)` on a module instance. All FASM feature names will be prepended with hierarchical prefixes.
+
+.. symbolator:: module.sim.v
+
+.. verilog-diagram:: module.sim.v
+   :type: netlistsvg
+   :module: MODULE
+
+.. no-license:: module.sim.v
+   :language: verilog
+   :caption: tests/fasm/features/no_modes/module.sim.v
+
+This results in the fasm features to be appended to the "fasm_features" pb_type metadata tag in the output XML:
+
+.. literalinclude:: module.model.xml
+   :language: xml
+   :caption: module.model.xml
+
+.. literalinclude:: module.pb_type.xml
+   :language: xml
+   :caption: module.pb_type.xml

tests/fasm/params/README.rst

@@ -0,0 +1,24 @@
+Binding FASM features to parameters
++++++++++++++++++++++++++++++++++++
+
+A fasm feature can be bound to a Verilog module parameter by applying the `(* FASM *)` attribute on the parameter definition. The feature name will have exactly the same name as the parameter and will be prepended with hierarchical prefixes.
+
+.. symbolator:: module.sim.v
+
+.. verilog-diagram:: module.sim.v
+   :type: netlistsvg
+   :module: MODULE
+
+.. no-license:: module.sim.v
+   :language: verilog
+   :caption: tests/fasm/prefix/module.sim.v
+
+The annotated parameters will be appended to the "fasm_params" section of the pb_type metadata:
+
+.. literalinclude:: module.model.xml
+   :language: xml
+   :caption: module.model.xml
+
+.. literalinclude:: module.pb_type.xml
+   :language: xml
+   :caption: module.pb_type.xml

tests/fasm/prefix/README.rst

@@ -0,0 +1,30 @@
+FASM prefix specification
++++++++++++++++++++++++++
+
+This example illustrates specifying FASM prefixes both for individual cells as well as for cell arrays.
+
+Complete FASM feature names are hierarchical. The hierarchy is built by concatenating prefixes assigned to pb_type in the pb_type hierarchy.
+
+In V2X a FASM prefix may be assigned to a cell instance via the `(* FASM_PREFIX *)` attribute. It is crucial that it is specified on instances, not on module definitions!
+
+Cell arrays can also be defined using generate statement. For a cell array the resulting "num_pb" value of the generated pb_type is equal to the array size. So is the required number of fasm prefixes. To accomodate for that multiple prefixes have to be specified in `(* FASM_PREFIX *)` as a semicolon separated list. The prefixes will be assigned to cells in the order they are given.
+
+.. symbolator:: parent.sim.v
+
+.. verilog-diagram:: parent.sim.v
+   :type: netlistsvg
+   :module: PARENT
+
+.. no-license:: parent.sim.v
+   :language: verilog
+   :caption: tests/fasm/prefix/parent.sim.v
+
+You may notice "fasm_prefix" metadata tags appended to pb_types
+
+.. literalinclude:: parent.model.xml
+   :language: xml
+   :caption: parent.model.xml
+
+.. literalinclude:: parent.pb_type.xml
+   :language: xml
+   :caption: parent.pb_type.xml