fix literalincludes and other path references in documentation

2020-03-16 12:06:59 -07:00
parent a3e12b96b0
commit ffb9c81ce2
12 changed files with 48 additions and 47 deletions
--- a/docs/Advanced-Concepts/Chip-Communication.rst
+++ b/docs/Advanced-Concepts/Chip-Communication.rst
@@ -111,7 +111,7 @@ FireSim FPGA-accelerated simulations use TSI by default as well.

 If you would like to build and simulate a Chipyard configuration with a DTM configured for DMI communication, then you must tie-off the TSI interface, and instantiate the `SimDTM`. Note that we use `WithTiedOffSerial ++ WithSimDebug` instead of `WithTiedOffDebug ++ WithSimSerial`.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: DmiRocket
    :end-before: DOC include end: DmiRocket
@@ -141,7 +141,7 @@ The configuration is very similar to a DMI-based configuration. The main differe
 is the addition of the ``WithJtagDTM`` config fragment that configures the instantiated DTM to use the JTAG protocol as the
 bringup method.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: JtagRocket
    :end-before: DOC include end: JtagRocket
--- a/docs/Customization/DMA-Devices.rst
+++ b/docs/Customization/DMA-Devices.rst
@@ -12,7 +12,7 @@ having the CPU poll data from the device, we may want to have the device write
 directly to the coherent memory system instead. For example, here is a device
 that writes zeros to the memory at a configured address.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/InitZero.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/InitZero.scala
    :language: scala

 .. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
@@ -26,12 +26,12 @@ For more info on creating TileLink client nodes, take a look at :ref:`Client Nod

 Once we've created our top-level module including the DMA widget, we can create a configuration for it as we did before.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/InitZero.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/InitZero.scala
    :language: scala
    :start-after: DOC include start: WithInitZero
    :end-before: DOC include end: WithInitZero

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: InitZeroRocketConfig
    :end-before: DOC include end: InitZeroRocketConfig
--- a/docs/Customization/Heterogeneous-SoCs.rst
+++ b/docs/Customization/Heterogeneous-SoCs.rst
@@ -13,7 +13,7 @@ When used together you can create a heterogeneous system.

 The following example shows a dual core BOOM with a single core Rocket.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/HeteroConfigs.scala
    :language: scala
    :start-after: DOC include start: DualBoomAndRocket
    :end-before: DOC include end: DualBoomAndRocket
@@ -72,7 +72,7 @@ Adding Hwachas
 Adding a Hwacha accelerator is as easy as adding the ``DefaultHwachaConfig`` so that it can setup the Hwacha parameters and add itself to the ``BuildRoCC`` parameter.
 An example of adding a Hwacha to all tiles in the system is below.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/HeteroConfigs.scala
    :language: scala
    :start-after: DOC include start: BoomAndRocketWithHwacha
    :end-before: DOC include end: BoomAndRocketWithHwacha
@@ -88,7 +88,7 @@ Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on
 For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles.
 An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/HeteroConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/HeteroConfigs.scala
    :language: scala
    :start-after: DOC include start: DualBoomAndRocketOneHwacha
    :end-before: DOC include end: DualBoomAndRocketOneHwacha
--- a/docs/Customization/Incorporating-Verilog-Blocks.rst
+++ b/docs/Customization/Incorporating-Verilog-Blocks.rst
@@ -57,7 +57,8 @@ and Verilog sources follow the prescribed directory layout.
        build.sbt
        src/main/
            scala/
-                GCD.scala
+                example/
+                    GCD.scala
            resources/
                vsrc/
                    GCDMMIOBlackBox.v
@@ -88,7 +89,7 @@ as the bitwidth of the GCD calculation does in this example.

 **Chisel BlackBox Definition**

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD blackbox
    :end-before: DOC include end: GCD blackbox
@@ -103,7 +104,7 @@ peripheral-specific traits into a ``TLRegisterRouter``. The ``params``
 member and ``HasRegMap`` base trait should look familiar from the
 previous memory-mapped GCD device example.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD instance regmap
    :end-before: DOC include end: GCD instance regmap
@@ -115,7 +116,7 @@ Defining a Chip with a BlackBox
 Since we've parameterized the GCD instantiation to choose between the
 Chisel and the Verilog module, creating a config is easy.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: GCDAXI4BlackBoxRocketConfig
    :end-before: DOC include end: GCDAXI4BlackBoxRocketConfig
--- a/docs/Customization/Keys-Traits-Configs.rst
+++ b/docs/Customization/Keys-Traits-Configs.rst
@@ -16,7 +16,7 @@ Keys specify some parameter which controls some custom widget. Keys should typic

 Keys should be defined and documented in sub-projects, since they generally deal with some specific block, and not system-level integration. (We make an exception for the example GCD widget).

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD key
    :end-before: DOC include end: GCD key
@@ -24,7 +24,7 @@ Keys should be defined and documented in sub-projects, since they generally deal
 The object within a key is typically a ``case class XXXParams``, which defines a set of parameters which some block accepts. For example, the GCD widget's ``GCDParams`` parameterizes its address, operand widths, whether the widget should be connected by Tilelink or AXI4, and whether the widget should use the blackbox-Verilog implementation, or the Chisel implementation.


-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD params
    :end-before: DOC include end: GCD params
@@ -42,7 +42,7 @@ Top-level traits should be defined and documented in subprojects, alongside thei

 Below we see the traits for the GCD example. The Lazy trait connects the GCD module to the Diplomacy graph, while the Implementation trait causes the ``Top`` to instantiate an additional port and concretely connect it to the GCD module.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD lazy trait
    :end-before: DOC include end: GCD imp trait
@@ -61,14 +61,14 @@ Config fragments set the keys to a non-default value. Together, the collection o

 For example, the ``WithGCD`` config fragment is parameterized by the type of GCD widget you want to instantiate. When this config fragment is added to a config, the ``GCDKey`` is set to a instance of ``GCDParams``, informing the previously mentioned traits to instantiate and connect the GCD widget appropriately.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD config fragment
    :end-before: DOC include end: GCD config fragment

 We can use this config fragment when composing our configs.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: GCDTLRocketConfig
    :end-before: DOC include end: GCDTLRocketConfig
--- a/docs/Customization/MMIO-Peripherals.rst
+++ b/docs/Customization/MMIO-Peripherals.rst
@@ -3,21 +3,21 @@
 MMIO Peripherals
 ==================

-The easiest way to create a MMIO peripheral is to use the ``TLRegisterRouter`` or ``AXI4RegisterRouter`` widgets, which abstracts away the details of handling the interconnect protocols and provides a convenient interface for specifying memory-mapped registers. Since Chipyard and Rocket Chip SoCs primarily use Tilelink as the on-chip interconnect protocol, this section will primarily focus on designing Tilelink-based peripherals. However, see ``generators/chipyard/src/main/scala/GCD.scala`` for how an example AXI4 based peripheral is defined and connected to the Tilelink graph through converters.
+The easiest way to create a MMIO peripheral is to use the ``TLRegisterRouter`` or ``AXI4RegisterRouter`` widgets, which abstracts away the details of handling the interconnect protocols and provides a convenient interface for specifying memory-mapped registers. Since Chipyard and Rocket Chip SoCs primarily use Tilelink as the on-chip interconnect protocol, this section will primarily focus on designing Tilelink-based peripherals. However, see ``generators/chipyard/src/main/scala/example/GCD.scala`` for how an example AXI4 based peripheral is defined and connected to the Tilelink graph through converters.

 To create a RegisterRouter-based peripheral, you will need to specify a parameter case class for the configuration settings, a bundle trait with the extra top-level ports, and a module implementation containing the actual RTL.

 For this example, we will show how to connect a MMIO peripheral which computes the GCD.
-The full code can be found in ``generators/chipyard/src/main/scala/GCD.scala``.
+The full code can be found in ``generators/chipyard/src/main/scala/example/GCD.scala``.

 In this case we use a submodule ``GCDMMIOChiselModule`` to actually perform the GCD. The ``GCDModule`` class only creates the registers and hooks them up using ``regmap``.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD chisel
    :end-before: DOC include end: GCD chisel

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD instance regmap
    :end-before: DOC include end: GCD instance regmap
@@ -51,7 +51,7 @@ The second set of arguments is the IO bundle constructor, which we create by ext
 The final set of arguments is the module constructor, which we create by extends ``TLRegModule`` with our module trait.
 Notice how we can create an analogous AXI4 version of our peripheral.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD router
    :end-before: DOC include end: GCD router
@@ -69,7 +69,7 @@ In the Rocket Chip cake, there are two kinds of traits: a ``LazyModule`` trait a
 The ``LazyModule`` trait runs setup code that must execute before all the hardware gets elaborated.
 For a simple memory-mapped peripheral, this just involves connecting the peripheral's TileLink node to the MMIO crossbar.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD lazy trait
    :end-before: DOC include end: GCD lazy trait
@@ -82,7 +82,7 @@ Also observe how we have to place additional AXI4 buffers and converters for the
 For peripherals which instantiate a concrete module, or which need to be connected to concrete IOs or wires, a matching concrete trait is necessary. We will make our GCD example output a ``gcd_busy`` signal as a top-level port to demonstrate. In the concrete module implementation trait, we instantiate the top level IO (a concrete object) and wire it to the IO of our lazy module.


-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
    :start-after: DOC include start: GCD imp trait
    :end-before: DOC include end: GCD imp trait
@@ -105,14 +105,14 @@ The ``TopModule`` class is the actual RTL that gets synthesized.



-And finally, we create a configuration class in ``generators/chipyard/src/main/scala/Configs.scala`` that uses the ``WithGCD`` config fragment defined earlier.
+And finally, we create a configuration class in ``generators/chipyard/src/main/scala/config/RocketConfigs.scala`` that uses the ``WithGCD`` config fragment defined earlier.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/GCD.scala
    :language: scala
-    :start-after: DOC include start: GCD fragment
-    :end-before: DOC include end: GCD fragment
+    :start-after: DOC include start: GCD config fragment
+    :end-before: DOC include end: GCD config fragment

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: GCDTLRocketConfig
    :end-before: DOC include end: GCDTLRocketConfig
--- a/docs/Customization/Memory-Hierarchy.rst
+++ b/docs/Customization/Memory-Hierarchy.rst
@@ -29,7 +29,7 @@ you can only use a single core and you cannot give the design an external DRAM.
 Note that these configurations fully remove the L2 cache and mbus.


-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: scratchpadrocket
    :end-before: DOC include end: scratchpadrocket
--- a/docs/Generators/Gemmini.rst
+++ b/docs/Generators/Gemmini.rst
@@ -9,7 +9,7 @@ To add a Gemmini unit to an SoC, you should add the ``gemmini.DefaultGemminiConf

 The example Chipyard config includes the following example SoC configuration which includes Gemmini:

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: GemminiRocketConfig
    :end-before: DOC include end: GemminiRocketConfig
--- a/docs/Generators/SHA3.rst
+++ b/docs/Generators/SHA3.rst
@@ -72,7 +72,7 @@ it can be mixed into a Rocket or BOOM core by overriding the
 generator. An example configuration highlighting the use of
 this config fragment is shown here:

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
   :language: scala
   :start-after: DOC include start: Sha3Rocket
   :end-before: DOC include end: Sha3Rocket
--- a/docs/Generators/SiFive-Generators.rst
+++ b/docs/Generators/SiFive-Generators.rst
@@ -20,8 +20,8 @@ To integrate one of these devices in your SoC, you will need to define a custom

 .. literalinclude:: ../../generators/chipyard/src/main/scala/ConfigFragments.scala
    :language: scala
-    :start-after: DOC include start: gpio mixin
-    :end-before: DOC include end: gpio mixin
+    :start-after: DOC include start: gpio config fragment
+    :end-before: DOC include end: gpio config fragment

 Additionally, if the device requires top-level IOs, you will need to define a config fragment to change the top-level configuration of your SoC.
 When adding a top-level IO, you should also be aware of whether it interacts with the test-harness.
@@ -31,7 +31,7 @@ This example instantiates a top-level module with include GPIO ports, and then t

 Finally, you add the relevant config fragment to the SoC config. For example:

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala
    :language: scala
    :start-after: DOC include start: GPIORocketConfig
    :end-before: DOC include end: GPIORocketConfig
--- a/docs/TileLink-Diplomacy-Reference/NodeTypes.rst
+++ b/docs/TileLink-Diplomacy-Reference/NodeTypes.rst
@@ -17,7 +17,7 @@ The L1 caches and DMA devices in RocketChip/Chipyard have client nodes.
 You can add a TileLink client node to your LazyModule using the TLHelper
 object from testchipip like so:

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyClient
    :end-before: DOC include end: MyClient
@@ -66,7 +66,7 @@ TileLink managers take requests from clients on the A channel and send
 responses back on the D channel. You can create a manager node using the
 TLHelper like so:

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyManager
    :end-before: DOC include end: MyManager
@@ -146,7 +146,7 @@ to the outputs unchanged. This node is mainly used to combine multiple
 nodes into a single node with multiple edges. For instance, say we have two
 client lazy modules, each with their own client node.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyClient1+MyClient2
    :end-before: DOC include end: MyClient1+MyClient2
@@ -154,21 +154,21 @@ client lazy modules, each with their own client node.
 Now we instantiate these two clients in another lazy module and expose their
 nodes as a single node.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyClientGroup
    :end-before: DOC include end: MyClientGroup

 We can also do the same for managers.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyManagerGroup
    :end-before: DOC include end: MyManagerGroup

 If we want to connect the client and manager groups together, we can now do this.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/NodeTypes.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/NodeTypes.scala
    :language: scala
    :start-after: DOC include start: MyClientManagerComplex
    :end-before: DOC include end: MyClientManagerComplex
--- a/docs/TileLink-Diplomacy-Reference/Register-Router.rst
+++ b/docs/TileLink-Diplomacy-Reference/Register-Router.rst
@@ -18,7 +18,7 @@ This section will focus on the second method.
 Basic Usage
 -----------

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MyDeviceController
    :end-before: DOC include end: MyDeviceController
@@ -56,7 +56,7 @@ register. The ``RegField`` interface also provides support for reading
 and writing ``DecoupledIO`` interfaces. For instance, you can implement a
 hardware FIFO like so.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MyQueueRegisters
    :end-before: DOC include end: MyQueueRegisters
@@ -71,7 +71,7 @@ You need not specify both read and write for a register. You can also create
 read-only or write-only registers. So for the previous example, if you wanted
 enqueue and dequeue to use different addresses, you could write the following.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MySeparateQueueRegisters
    :end-before: DOC include end: MySeparateQueueRegisters
@@ -93,7 +93,7 @@ You can also create registers using functions. Say, for instance, that you
 want to create a counter that gets incremented on a write and decremented on
 a read.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MyCounterRegisters
    :end-before: DOC include end: MyCounterRegisters
@@ -107,7 +107,7 @@ You can also pass functions that decouple the read/write request and response.
 The request will appear as a decoupled input and the response as a decoupled
 output. So for instance, if we wanted to do this for the previous example.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MyCounterReqRespRegisters
    :end-before: DOC include end: MyCounterReqRespRegisters
@@ -131,7 +131,7 @@ change the protocol being used. For instance, in the first example in
 :ref:`Basic Usage`, you could simply change the ``TLRegisterNode`` to
 and ``AXI4RegisterNode``.

-.. literalinclude:: ../../generators/chipyard/src/main/scala/RegisterNodeExample.scala
+.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala
    :language: scala
    :start-after: DOC include start: MyAXI4DeviceController
    :end-before: DOC include end: MyAXI4DeviceController