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

Address generator unification PR reviews

Browse Source
This commit is contained in:
Jerry Zhao
2020-02-23 22:53:14 -08:00
parent 941c217fbe
commit 708a5fb9a6
17 changed files with 153 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/Advanced-Concepts/Chip-Communication.rst
View File

@@ -109,7 +109,7 @@ reminder, to run a software RTL simulation, run:
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 ++ WithSimDTM` instead of `WithTiedOffDebug ++ WithSimSerial`.
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
:language: scala

4
docs/Chipyard-Basics/Configs-Parameters-Mixins.rst
View File

@@ -91,8 +91,8 @@ lazy module implementation performs the actual Chisel RTL elaboration.
In the ``Top`` example class, the "outer" ``Top`` instantiates the "inner"
``TopModule`` as a lazy module implementation. This delays immediate elaboration
of the module until all logical connections are determined and all configuration information is exchanged.
The ``Syatem`` outer base class, as well as the
``CanHavePeripheryX`` outer traits contain code to perform high-level logical
The ``System`` outer base class, as well as the
``CanHavePeriphery<X>`` outer traits contain code to perform high-level logical
connections. For example, the ``CanHavePeripherySerial`` outer trait contains code
to optionally lazily instantiate the ``SerialAdapter``, and connect the ``SerialAdapter``'s
TileLink node to the Front bus.

25
docs/Customization/IOBinders.rst Normal file
View File

@@ -0,0 +1,25 @@
IOBinders
=========
In Chipyard we use a special ``Parameters`` key, ``IOBinders`` to determine what modules to bind to the IOs of a ``Top`` in the ``TestHarness``.
.. literalinclude:: ../../generators/chipyard/src/main/scala/IOBinders.scala
:language: scala
:start-after: DOC include start: IOBinders
:end-before: DOC include end: IOBinders
This special key solves the problem of duplicating test-harnesses for each different ``Top`` type.
You could just as well create a custom harness module that attaches IOs explicitly. Instead, the IOBinders key provides a map from Scala traits to attachment behaviors.
For example, the ``WithSimAXIMemTiedOff`` IOBinder specifies that any ``Top`` which matches ``CanHaveMasterAXI4MemPortModuleImp`` will have a ``SimAXIMem`` connected.
.. literalinclude:: ../../generators/chipyard/src/main/scala/IOBinders.scala
:language: scala
:start-after: DOC include start: WithSimAXIMem
:end-before: DOC include end: WithSimAXIMem
These classes are all ``Config`` objects, which can be mixed into the configs to specify IO connection behaviors.
There are two macros for generating these ``Configs``. ``OverrideIOBinder`` overrides any existing behaviors set for a particular IO in the ``Config`` object. This macro is frequently used because typically top-level IOs drive or are driven by only one source, so a composition of ``IOBinders`` does not make sense. The ``ComposeIOBinder`` macro provides the functionality of not overriding existing behaviors.

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

@@ -9,89 +9,30 @@ The L1 Caches
Each CPU tile has an L1 instruction cache and L1 data cache. The size and
associativity of these caches can be configured. The default ``RocketConfig``
uses 16 KiB, 4-way set-associative instruction and data caches. However,
if you use the ``NMedCores`` or ``NSmallCores`` configurations, you can
if you use the ``WithNMedCores`` or ``WithNSmallCores`` configurations, you can
configure 4 KiB direct-mapped caches for L1I and L1D.
.. code-block:: scala
class SmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithInclusiveCache ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++ // small rocket cores
new freechips.rocketchip.system.BaseConfig)
class MediumRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithInclusiveCache ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNMediumCores(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.
mixins for those too. See :ref:`Mixins` for how to add these to a custom ``Config``
.. code-block:: scala
import freechips.rocketchip.subsystem.{WithL1ICacheSets, WithL1DCacheSets, WithL1ICacheWays, WithL1DCacheWays}
class MyL1RocketConfig extends Config(
new freechips.rocketchip.subsystem.WithL1ICacheSets(128) ++ // change rocket I$
new freechips.rocketchip.subsystem.WithL1ICacheWays(2) ++ // change rocket I$
new freechips.rocketchip.subsystem.WithL1DCacheSets(128) ++ // change rocket D$
new freechips.rocketchip.subsystem.WithL1DCacheWays(2) ++ // change rocket D$
new RocketConfig)
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,
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.
.. code-block:: scala
class ScratchpadSmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithNMemoryChannels(0) ++
new freechips.rocketchip.subsystem.WithNBanks(0) ++
new freechips.rocketchip.subsystem.WithScratchpadsOnly ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
.. literalinclude:: ../../generators/chipyard/src/main/scala/RocketConfigs.scala
:language: scala
:start-after: DOC include start: scratchpadrocket
:end-before: DOC include end: scratchpadrocket
This configuration fully removes the L2 cache and memory bus by setting the
@@ -121,27 +62,8 @@ To make such a configuration, you can just copy the definition of
list of included mixims.
If you want to reduce the resources used even further, you can configure
the Broadcast Hub to use a bufferless design.
.. code-block:: scala
class NoL2SmallRocketConfig extends Config(
new chipyard.iobinders.WithUARTAdapter ++
new chipyard.iobinders.WithTieOffInterrupts ++
new chipyard.iobinders.WithSimAXIMem ++
new chipyard.iobinders.WithTiedOffDebug ++
new chipyard.iobinders.WithSimSerial ++
new testchipip.WithTSI ++
new chipyard.config.WithNoGPIO ++
new chipyard.config.WithBootROM ++
new chipyard.config.WithUART ++
new chipyard.config.WithL2TLBs(1024) ++
new freechips.rocketchip.subsystem.WithBufferlessBroadcastHub ++
new freechips.rocketchip.subsystem.WithNoMMIOPort ++
new freechips.rocketchip.subsystem.WithNoSlavePort ++
new freechips.rocketchip.subsystem.WithNExtTopInterrupts(0) ++
new freechips.rocketchip.subsystem.WithNSmallCores(1) ++
new freechips.rocketchip.system.BaseConfig)
the Broadcast Hub to use a bufferless design. This mixin is
``freechips.rocketchip.subsystem.WithBufferlessBroadcastHub``.
The Outer Memory System
@@ -156,11 +78,7 @@ number of DRAM channels is restricted to powers of two.
.. code-block:: scala
import freechips.rocketchip.subsystem.WithNMemoryChannels
class DualChannelRocketConfig extends Config(
new freechips.rocketchip.subsystem.WithNMemoryChannels(2) ++
new RocketConfig)
new freechips.rocketchip.subsystem.WithNMemoryChannels(2)
In VCS and Verilator simulation, the DRAM is simulated using the

1
docs/Customization/index.rst
View File

@@ -42,3 +42,4 @@ We recommend reading all these pages in order. Hit next to get started!
Memory-Hierarchy
Boot-Process
Firrtl-Transforms
IOBinders

2
docs/Makefile
View File

@@ -2,7 +2,7 @@
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXOPTS = -w warnings.txt
SPHINXBUILD = python -msphinx
SPHINXPROJ = Chipyard
SOURCEDIR = .

56
docs/Simulation/FPGA-Accelerated-Simulation.rst
View File

@@ -44,47 +44,19 @@ familiar with FireSim, please return to the `FireSim Docs
<https://docs.fires.im/en/latest/Initial-Setup/Setting-up-your-Manager-Instance.html#completing-setup-using-the-manager>`__,
and proceed with the rest of the tutorial.
Current Limitations:
++++++++++++++++++++
FireSim integration in Chipyard is still a work in progress. Presently, you
cannot build a FireSim simulator from any generator project in Chipyard except ``firechip``,
which properly invokes MIDAS on the target RTL.
In the interim, workaround this limitation by importing Config and Module
classes from other generator projects into FireChip. For example, assuming you Chipyard
config looks as following:
.. code-block:: scala
class CustomConfig extends Config(
new WithInclusiveCache ++
new myproject.MyCustomConfig ++
new DefaultRocketConfig
)
Then the equivalent FireChip config (in ``generators/firechip/src/main/scala/TargetConfigs.scala``) based on ``FireSimRocketChipConfig``
will look as follows:
.. code-block:: scala
class FireSimCustomConfig extends Config(
new WithBootROM ++
new WithPeripheryBusFrequency(BigInt(3200000000L)) ++
new WithExtMemSize(0x400000000L) ++ // 16GB
new WithoutTLMonitors ++
new WithUARTKey ++
new WithNICKey ++
new WithBlockDevice ++
new WithRocketL2TLBs(1024) ++
new WithPerfCounters ++
new WithoutClockGating ++
new WithInclusiveCache ++
new myproject.MyCustomConfig ++
new freechips.rocketchip.system.DefaultConfig)
Running your Design in FireSim
------------------------------
Converting a Chipyard config (one in ``chipyard/src/main/scala`` to run in FireSim is simple. We are using the same target (top) RTL, and only need to specify a new set of connection behaviors for the IOs of that module. Simply create a matching config within ``generators/firechip/src/main/scala/TargetConfigs`` that inherits your config defined in ``chipyard``.
You should then be able to refer to those classes or an alias of them in your ``DESIGN`` or ``TARGET_CONFIG``
variables. Note that if your target machine has I/O not provided in the default
FireChip targets (see ``generators/firechip/src/main/scala/Targets.scala``) you may need
to write a custom bridge.
.. literalinclude:: ../../generators/firechip/src/main/scala/TargetConfigs.scala
:language: scala
:start-after: DOC include start: firesimconfig
:end-before: DOC include end: firesimconfig
Only 3 additional config-mixins are needed.
* ``WithFireSimConfigTweaks`` modifies your design to better fit the FireSim usage model. For example, FireSim designs typically include a UART. Technically, adding this in is optional, but *strongly* recommended.
* ``WithDefaultMemModel`` sets the external memory model in the FireSim simulation. See the FireSim documentation for details.
* ``WithDefaultFireSimBridges`` sets the ``IOBinders`` key to use FireSim's Bridge system, which can drive target IOs with software bridge models running on the simulation host. See the FireSIm documnetation for details.