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

Update docs

Browse Source
This commit is contained in:
Jerry Zhao
2020-02-13 11:40:10 -08:00
parent 0f56c4ce44
commit c12819eb52
28 changed files with 247 additions and 301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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/example/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/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/example/src/main/scala/GCD.scala``.
The full code can be found in ``generators/chipyard/src/main/scala/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/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD chisel
:end-before: DOC include end: GCD chisel
.. literalinclude:: ../../generators/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/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/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/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/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/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/example/src/main/scala/GCD.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD imp trait
:end-before: DOC include end: GCD imp trait
@@ -91,9 +91,9 @@ Constructing the Top and Config
-------------------------------
Now we want to mix our traits into the system as a whole.
This code is from ``generators/example/src/main/scala/Top.scala``.
This code is from ``generators/chipyard/src/main/scala/Top.scala``.
.. literalinclude:: ../../generators/example/src/main/scala/Top.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/Top.scala
:language: scala
:start-after: DOC include start: Top
:end-before: DOC include end: Top
@@ -105,14 +105,14 @@ The ``TopModule`` class is the actual RTL that gets synthesized.
And finally, we create a configuration class in ``generators/example/src/main/scala/Configs.scala`` that uses the ``WithGCD`` mixin defined earlier.
And finally, we create a configuration class in ``generators/chipyard/src/main/scala/Configs.scala`` that uses the ``WithGCD`` mixin defined earlier.
.. literalinclude:: ../../generators/example/src/main/scala/ConfigMixins.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/GCD.scala
:language: scala
:start-after: DOC include start: GCD mixin
:end-before: DOC include end: GCD mixin
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: GCDTLRocketConfig
:end-before: DOC include end: GCDTLRocketConfig