wu-arch/chipyard
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fix literalincludes and other path references in documentation

Browse Source
This commit is contained in:
Howard Mao
2020-03-16 12:06:59 -07:00
parent a3e12b96b0
commit ffb9c81ce2
12 changed files with 48 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/Customization/DMA-Devices.rst
View File

@@ -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

6
docs/Customization/Heterogeneous-SoCs.rst
View File

@@ -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

9
docs/Customization/Incorporating-Verilog-Blocks.rst
View File

@@ -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

10
docs/Customization/Keys-Traits-Configs.rst
View File

@@ -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

24
docs/Customization/MMIO-Peripherals.rst
View File

@@ -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

2
docs/Customization/Memory-Hierarchy.rst
View File

@@ -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