Merge pull request #599 from ucb-bar/dev

Chipyard 1.4.0 Release

docs/TileLink-Diplomacy-Reference/NodeTypes.rst

@@ -1,3 +1,5 @@
+.. _node_types:
+
 TileLink Node Types
 ===================
 
@@ -57,7 +59,7 @@ TileLink messages.
 
 The ``edge`` object represents the edge of the Diplomacy graph. It contains
 some useful helper functions which will be documented in
-:ref:`TileLink Edge Object Methods`.
+:ref:`TileLink-Diplomacy-Reference/EdgeFunctions:TileLink Edge Object Methods`.
 
 Manager Node
 ------------
@@ -114,7 +116,7 @@ most MMIO peripherals should set it to.
 
 The next six arguments start with ``support`` and determine the different
 A channel message types that the manager can accept. The definitions of the
-message types are explained in :ref:`TileLink Edge Object Methods`.
+message types are explained in :ref:`TileLink-Diplomacy-Reference/EdgeFunctions:TileLink Edge Object Methods`.
 The ``TransferSizes`` case class specifies the range of logical sizes (in bytes)
 that the manager can accept for the particular message type. This is an inclusive
 range and all logical sizes must be powers of two. So in this case, the manager
@@ -135,7 +137,7 @@ to handle TileLink requests, it is usually much easier to use a register node.
 This type of node provides a ``regmap`` method that allows you to specify
 control/status registers and automatically generates the logic to handle the
 TileLink protocol. More information about how to use register nodes can be
-found in :ref:`Register Router`.
+found in :ref:`TileLink-Diplomacy-Reference/Register-Router:Register Router`.
 
 Identity Node
 -------------
@@ -174,7 +176,7 @@ If we want to connect the client and manager groups together, we can now do this
     :end-before: DOC include end: MyClientManagerComplex
 
 The meaning of the ``:=*`` operator is explained in more detail in the
-:ref:`Diplomacy Connectors` section. In summary, it connects two nodes together
+:ref:`TileLink-Diplomacy-Reference/Diplomacy-Connectors:Diplomacy Connectors` section. In summary, it connects two nodes together
 using multiple edges. The edges in the identity node are assigned in order,
 so in this case ``client1.node`` will eventually connect to ``manager1.node``
 and ``client2.node`` will connect to ``manager2.node``.
@@ -190,7 +192,7 @@ produces the same number of outputs. However, unlike the identity node, the
 adapter node does not simply pass the connections through unchanged.
 It can change the logical and physical interfaces between input and output and
 rewrite messages going through. RocketChip provides a library of adapters,
-which are catalogued in :ref:`Diplomatic Widgets`.
+which are catalogued in :ref:`TileLink-Diplomacy-Reference/Widgets:Diplomatic Widgets`.
 
 You will rarely need to create an adapter node yourself, but the invocation is
 as follows.

docs/TileLink-Diplomacy-Reference/Register-Router.rst

@@ -32,7 +32,7 @@ The default value is 4 bytes. The ``concurrency`` argument is the size of the
 internal queue for TileLink requests. By default, this value is 0, which means
 there will be no queue. This value must be greater than 0 if you wish to
 decoupled requests and responses for register accesses. This is discussed
-in :ref:`Using Functions`.
+in :ref:`TileLink-Diplomacy-Reference/Register-Router:Using Functions`.
 
 The main way to interact with the node is to call the ``regmap`` method, which
 takes a sequence of pairs. The first element of the pair is an offset from the
@@ -128,7 +128,7 @@ Register Routers for Other Protocols
 
 One useful feature of the register router interface is that you can easily
 change the protocol being used. For instance, in the first example in
-:ref:`Basic Usage`, you could simply change the ``TLRegisterNode`` to
+:ref:`TileLink-Diplomacy-Reference/Register-Router:Basic Usage`, you could simply change the ``TLRegisterNode`` to
 and ``AXI4RegisterNode``.
 
 .. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala

docs/TileLink-Diplomacy-Reference/Widgets.rst

@@ -1,3 +1,5 @@
+.. _diplomatic_widgets:
+
 Diplomatic Widgets
 ==================
 
@@ -79,7 +81,7 @@ The arguments for the five-argument constructor are
 AXI4Buffer
 ----------
 
-Similar to the :ref:`TLBuffer`, but for AXI4. It also takes ``BufferParams`` objects
+Similar to the :ref:`TileLink-Diplomacy-Reference/Widgets:TLBuffer`, but for AXI4. It also takes ``BufferParams`` objects
 as arguments.
 
 **Arguments:**
@@ -198,10 +200,11 @@ transactions.
 AXI4Fragmenter
 --------------
 
-The AXI4Fragmenter is similar to the :ref:`TLFragmenter`, except it can only
-break multi-beat AXI4 transactions into single-beat transactions. This
-effectively serves as an AXI4 to AXI4-Lite converter. The constructor for this
-widget does not take any arguments.
+The AXI4Fragmenter is similar to the :ref:`TileLink-Diplomacy-Reference/Widgets:TLFragmenter`.
+The AXI4Fragmenter slices all AXI accesses into simple power-of-two sized and aligned transfers
+of the largest size supported by the manager. This makes it suitable as a first stage transformation
+to apply before an AXI4=>TL bridge. It also makes it suitable for placing after TL=>AXI4 bridge
+driving an AXI-lite slave.
 
 **Example Usage:**
 
@@ -235,7 +238,7 @@ you will want to use a TLSourceShrinker.
 AXI4IdIndexer
 -------------
 
-The AXI4 equivalent of :ref:`TLSourceShrinker`. This limits the number of
+The AXI4 equivalent of :ref:`TileLink-Diplomacy-Reference/Widgets:TLSourceShrinker`. This limits the number of
 AWID/ARID bits in the slave AXI4 interface. Useful for connecting to external
 or black box AXI4 ports.
 
@@ -255,7 +258,7 @@ or black box AXI4 ports.
 
 The AXI4IdIndexer will create a ``user`` field on the slave interface, as it
 stores the ID of the master requests in this field. If connecting to an AXI4
-interface that doesn't have a ``user`` field, you'll need to use the :ref:`AXI4UserYanker`.
+interface that doesn't have a ``user`` field, you'll need to use the :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker`.
 
 TLWidthWidget
 -------------
@@ -299,7 +302,7 @@ The possible values of ``policy`` are:
    ordering guaranteed
  - ``TLFIFOFixer.allVolatile`` - All managers that have a RegionType of
    ``VOLATILE``, ``PUT_EFFECTS``, or ``GET_EFFECTS`` will have ordering
-   guaranteed (see :ref:`Manager Node` for explanation of region types).
+   guaranteed (see :ref:`TileLink-Diplomacy-Reference/NodeTypes:Manager Node` for explanation of region types).
 
 TLXbar and AXI4Xbar
 -------------------
@@ -375,14 +378,14 @@ override the default arguments of the constructors for these widgets.
         AXI4Fragmenter() :=
         axi4master.node
 
-You will need to add an :ref:`AXI4Deinterleaver` after the TLToAXI4 converter
+You will need to add an :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4Deinterleaver` after the TLToAXI4 converter
 because it cannot deal with interleaved read responses. The TLToAXI4 converter
 also uses the AXI4 user field to store some information, so you will need an
-:ref:`AXI4UserYanker` if you want to connect to an AXI4 port without user
+:ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker` if you want to connect to an AXI4 port without user
 fields.
 
 Before you connect an AXI4 port to the AXI4ToTL widget, you will need to
-add an :ref:`AXI4Fragmenter` and :ref:`AXI4UserYanker` because the converter cannot
+add an :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4Fragmenter` and :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker` because the converter cannot
 deal with multi-beat transactions or user fields.
 
 TLROM

docs/TileLink-Diplomacy-Reference/index.rst

@@ -1,3 +1,5 @@
+.. _tilelink_and_diplomacy:
+
 TileLink and Diplomacy Reference
 ================================