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

[docs] update documentation [ci skip] (#393)

Browse Source
This commit is contained in:
Abraham Gonzalez
2020-01-23 13:36:21 -08:00
committed by GitHub
parent 44883b238b
commit 1859054f73
12 changed files with 117 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Customization/Boot-Process.rst
View File

@@ -17,7 +17,7 @@ The BootROM address space starts at ``0x10000`` (determined by the ``BootROMPara
The Chisel generator encodes the assembled instructions into the BootROM
hardware at elaboration time, so if you want to change the BootROM code, you
will need to run ``make`` in the bootrom directory and then regenerate the
verilog. If you don't want to overwrite the existing ``bootrom.S``, you can
Verilog. If you don't want to overwrite the existing ``bootrom.S``, you can
also point the generator to a different bootrom image by overriding the
``BootROMParams`` key in the configuration.

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

@@ -19,7 +19,7 @@ The following example shows a dual core BOOM with a single core Rocket.
:end-before: DOC include end: DualBoomAndRocket
In this example, the ``WithNBoomCores`` and ``WithNBigCores`` mixins set up the default parameters for the multiple BOOM and Rocket cores, respectively.
However, for BOOM, an extra mixin called ``LargeBoomConfig`` is added to override the default parameters with a different set of more common default parameters.
However, for BOOM, an extra mixin called ``WithLargeBooms`` is added to override the default parameters with a different set of more common default parameters.
This mixin applies to all BOOM cores in the system and changes the parameters for each.
Great! Now you have a heterogeneous setup with BOOMs and Rockets.
@@ -55,8 +55,12 @@ Then you could use this new mixin like the following.
.. code-block:: scala
class SixCoreConfig extends Config(
new WithTop ++
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new WithHeterCoresSetup ++
new freechips.rocketchip.system.BaseConfig)

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

@@ -61,7 +61,7 @@ and Verilog sources follow the prescribed directory layout.
resources/
vsrc/
GCDMMIOBlackBox.v
Defining a Chisel BlackBox
--------------------------
@@ -78,11 +78,11 @@ Of particular interest is the fact that parameterized Verilog modules
can be passed the full space of possible parameter values. These
values may depend on elaboration-time values in the Chisel generator,
as the bitwidth of the GCD calculation does in this example.
**Verilog GCD port list and parameters**
.. literalinclude:: ../../generators/example/src/main/resources/vsrc/GCDMMIOBlackBox.v
:language: verilog
:language: Verilog
:start-after: DOC include start: GCD portlist
:end-before: DOC include end: GCD portlist
@@ -113,7 +113,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.
Chisel and the Verilog module, creating a config is easy.
.. literalinclude:: ../../generators/example/src/main/scala/RocketConfigs.scala
:language: scala

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

@@ -21,7 +21,7 @@ Keys should be defined and documented in sub-projects, since they generally deal
:start-after: DOC include start: GCD key
:end-before: DOC include end: GCD key
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.
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/example/src/main/scala/GCD.scala
@@ -95,7 +95,7 @@ For example, conside a config that contains the mixins ``WithGPIO ++ WithTSI``.
When ``WithGPIO ++ WithTSI`` is evaluated right to left, the call to ``up(BuildTop, site)`` in ``WithGPIO`` will reference the function defined in the ``BuildTop`` key of ``WithTSI``. Thus, at elaboration time, when the ``BuildTop`` function is called by the ``TestHarness``, first the ``BuildTop`` function in ``WithTSI`` will be evaluated. This connects the ``success`` signal of the ``TestHarness`` to the ``SerialAdapter`` enabled by ``WithTSI``. Then, the rest of the code in the ``BuildTop`` function of ``WithGPIO`` will execute, tieing off the top-level GPIO input pins. Thus the evaluation of the ``BuildTop`` functions in a completed config is "right-to-left", matching how the evaluation of the mixins at compile-time is also "right-to-left".
.. warning::
Note that in some cases, the ordering and duplication of mixins which extend ``BuildTop`` will have unintended consequences.
In some cases, the ordering and duplication of mixins which extend ``BuildTop`` will have unintended consequences.
For example, ``WithTSI ++ WithTSI`` will attempt to generate and connect two ``SimSerial`` widgets in the ``TestHarness``,
which will likely break the simulation.
In general, you should avoid attaching multiple mixins which interface to the same top-level ports.

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

@@ -127,7 +127,7 @@ Now we can test that the GCD is working. The test program is in ``tests/gcd.c``.
This just writes out to the registers we defined earlier.
The base of the module's MMIO region is at 0x2000 by default.
This will be printed out in the address map portion when you generate the verilog code.
This will be printed out in the address map portion when you generate the Verilog code.
You can also see how this changes the emitted ``.json`` addressmap files in ``generated-src``.
Compiling this program with ``make`` produces a ``gcd.riscv`` executable.

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

@@ -15,18 +15,24 @@ configure 4 KiB direct-mapped caches for L1I and L1D.
.. code-block:: scala
class SmallRocketConfig extends Config(
new WithTop ++ // use default top
new WithBootROM ++ // use default bootrom
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ // small rocket cores
new freechips.rocketchip.system.BaseConfig)
class SmallRocketConfig extends Config(
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new RocketConfig)
class MediumRocketConfig extends Config(
new freechips.rocketchip.subsystem.WithNMedCores(1) ++
new RocketConfig)
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNMedCores(1) ++ // medium rocket cores
new freechips.rocketchip.system.BaseConfig)
If you only want to change the size or associativity, there are configuration
mixins for those too.
@@ -36,11 +42,18 @@ mixins for those too.
import freechips.rocketchip.subsystem.{WithL1ICacheSets, WithL1DCacheSets, WithL1ICacheWays, WithL1DCacheWays}
class MyL1RocketConfig extends Config(
new WithL1ICacheSets(128) ++
new WithL1ICacheWays(2) ++
new WithL1DCacheSets(128) ++
new WithL1DCacheWays(2) ++
new RocketConfig)
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new WithL1ICacheSets(128) ++ // change rocket I$
new WithL1ICacheWays(2) ++ // change rocket I$
new WithL1DCacheSets(128) ++ // change rocket D$
new WithL1DCacheWays(2) ++ // change rocket D$
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
You can also configure the L1 data cache as an data scratchpad instead.
However, there are some limitations on this. If you are using a data scratchpad,
@@ -49,18 +62,22 @@ Note that these configurations fully remove the L2 cache and mbus.
.. code-block:: scala
class SmallRocketConfigNoL2 extends Config(
new WithTop ++ // use default top
new WithBootROM ++ // use default bootrom
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
class SmallRocketConfigNoL2 extends Config(
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
class ScratchpadRocketConfig extends Config(
new freechips.rocketchip.subsystem.WithNoMemPort ++
new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++
new freechips.rocketchip.subsystem.WithNBanks(0) ++
new freechips.rocketchip.subsystem.WithScratchpadsOnly ++
new SmallRocketConfigNoL2)
new freechips.rocketchip.subsystem.WithNoMemPort ++
new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++
new freechips.rocketchip.subsystem.WithNBanks(0) ++
new freechips.rocketchip.subsystem.WithScratchpadsOnly ++
new SmallRocketConfigNoL2)
This configuration fully removes the L2 cache and memory bus by setting the
number of channels and number of banks to 0.
@@ -79,13 +96,19 @@ and the number of banks must be powers of 2.
import freechips.rocketchip.subsystem.WithInclusiveCache
# Create an SoC with 1 MB, 4-way, 4-bank cache
class MyCacheRocketConfig extends Config(
new WithInclusiveCache(
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new WithInclusiveCache( // add 1MB, 4-way, 4-bank cache
capacityKB = 1024,
nWays = 4,
nBanks = 4) ++
new RocketConfig)
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
The Broadcast Hub
-----------------
@@ -99,13 +122,15 @@ list of included mixims.
.. code-block:: scala
import freechips.rocketchip.subsystem.{WithNBigCores, BaseConfig}
class CachelessRocketConfig extends Config(
new WithTop ++
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithNBigCores(1) ++
new BaseConfig)
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNBigCores(1) ++
new freechips.rocketchip.system.BaseConfig)
If you want to reduce the resources used even further, you can configure
the Broadcast Hub to use a bufferless design.
@@ -133,8 +158,15 @@ number of DRAM channels is restricted to powers of two.
import freechips.rocketchip.subsystem.WithNMemoryChannels
class DualChannelRocketConfig extends Config(
new WithNMemoryChannels(2) ++
new RocketConfig)
new WithTSI ++
new WithNoGPIO ++
new WithBootROM ++
new WithUART ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new WithNMemoryChannels(2) ++ // multi-channel outer mem
new freechips.rocketchip.subsystem.WithNBigCores(1) ++
new freechips.rocketchip.system.BaseConfig)
In VCS and Verilator simulation, the DRAM is simulated using the
``SimAXIMem`` module, which simply attaches a single-cycle SRAM to each

2
docs/Customization/index.rst
View File

@@ -17,7 +17,7 @@ These guides will walk you through customization of your system-on-chip:
- Connect widgets which act as TileLink masters
- Adding custom blackboxed verilog to a Chipyard design
- Adding custom blackboxed Verilog to a Chipyard design
We also provide information on: