Initial Commit - Forked from PeakRDL-regblock @ a440cc19769069be831d267505da4f3789a26695

docs/hwif.rst

@@ -0,0 +1,61 @@
+Hardware Interface
+------------------
+
+The generated register block will present the entire hardware interface to the user
+using two struct ports:
+
+* ``hwif_in``
+* ``hwif_out``
+
+All field inputs and outputs as well as signals are consolidated into these
+struct ports. The presence of each depends on the specific contents of the design
+being exported.
+
+
+Using structs for the hardware interface has the following benefits:
+
+* Preserves register map component grouping, arrays, and hierarchy.
+* Avoids naming collisions and cumbersome signal name flattening.
+* Allows for more natural mapping and distribution of register block signals to a design's hardware components.
+* Use of unpacked arrays/structs prevents common assignment mistakes as they are enforced by the compiler.
+
+
+Structs are organized as follows: ``hwif_out.<heir_path>.<feature>``
+
+For example, a simple design such as:
+
+.. code-block:: systemrdl
+
+        addrmap my_design {
+            reg {
+                field {
+                    sw = rw;
+                    hw = rw;
+                    we;
+                } my_field;
+            } my_reg[2];
+        };
+
+... results in the following struct members:
+
+.. code-block:: text
+
+    hwif_out.my_reg[0].my_field.value
+    hwif_in.my_reg[0].my_field.next
+    hwif_in.my_reg[0].my_field.we
+    hwif_out.my_reg[1].my_field.value
+    hwif_in.my_reg[1].my_field.next
+    hwif_in.my_reg[1].my_field.we
+
+For brevity in this documentation, hwif features will be described using shorthand
+notation that omits the hierarchical path: ``hwif_out..<feature>``
+
+
+.. important::
+
+    The PeakRDL tool makes no guarantees on the field order of the hwif structs.
+    For this reason, it is strongly recommended to always access struct members
+    directly, by name.
+
+    If using the SystemVerilog streaming operator to assign the hwif struct to a
+    packed vector, be extremely careful to avoid assumptions on the resulting bit-position of a field.