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

docs label disambiguation

Browse Source
This commit is contained in:
alonamid
2021-01-08 20:11:21 -08:00
parent 558cff7469
commit 7e092c655b
27 changed files with 72 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -54,7 +54,7 @@ sends the TSI command recieved by the simulation stub into the DUT which then co
command into a TileLink request. This conversion is done by the ``SerialAdapter`` module
(located in the ``generators/testchipip`` project). In simulation, FESVR
resets the DUT, writes into memory the test program, and indicates to the DUT to start the program
through an interrupt (see :ref:`Chipyard Boot Process`). Using TSI is currently the fastest
through an interrupt (see :ref:`customization/Boot-Process:Chipyard Boot Process`). Using TSI is currently the fastest
mechanism to communicate with the DUT in simulation.
In the case of a chip tapeout bringup, TSI commands can be sent over a custom communication
@@ -96,7 +96,7 @@ Starting the TSI or DMI Simulation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
All default Chipyard configurations use TSI to communicate between the simulation and the simulated SoC/DUT. Hence, when running a
software RTL simulation, as is indicated in the :ref:`Software RTL Simulation` section, you are in-fact using TSI to communicate with the DUT. As a
software RTL simulation, as is indicated in the :ref:`simulation/Software-RTL-Simulation:Software RTL Simulation` section, you are in-fact using TSI to communicate with the DUT. As a
reminder, to run a software RTL simulation, run:
.. code-block:: bash

4
docs/Advanced-Concepts/Debugging-BOOM.rst
View File

@@ -1,8 +1,8 @@
Debugging BOOM
======================
In addition to the default debugging techniques specified in :ref:`Debugging RTL`,
single-core BOOM designs can utilize the Dromajo co-simulator (see :ref:`Dromajo`)
In addition to the default debugging techniques specified in :ref:`Advanced-Concepts/Debugging-RTL:Debugging RTL`,
single-core BOOM designs can utilize the Dromajo co-simulator (see :ref:`Tools/Dromajo:Dromajo`)
to verify functionality.
.. warning:: Dromajo currently only works in single-core BOOM systems without accelerators.

2
docs/Advanced-Concepts/Top-Testharness.rst
View File

@@ -58,7 +58,7 @@ Tops
A SoC Top then extends the ``System`` class with traits for custom components.
In Chipyard, this includes things like adding a NIC, UART, and GPIO as well as setting up the hardware for the bringup method.
Please refer to :ref:`Communicating with the DUT` for more information on these bringup methods.
Please refer to :ref:`Advanced-Concepts/Chip-Communication:Communicating with the DUT` for more information on these bringup methods.
TestHarness
-------------------------

24
docs/Chipyard-Basics/Chipyard-Components.rst
View File

@@ -14,15 +14,15 @@ Processor Cores
**Rocket Core**
An in-order RISC-V core.
See :ref:`Rocket Core` for more information.
See :ref:`Generators/Rocket:Rocket Core` for more information.
**BOOM (Berkeley Out-of-Order Machine)**
An out-of-order RISC-V core.
See :ref:`Berkeley Out-of-Order Machine (BOOM)` for more information.
See :ref:`Generators/BOOM:Berkeley Out-of-Order Machine (BOOM)` for more information.
**CVA6 Core**
An in-order RISC-V core written in System Verilog. Previously called Ariane.
See :ref:`CVA6 Core` for more information.
See :ref:`Generators/CVA6:CVA6 Core` for more information.
Accelerators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -31,7 +31,7 @@ Accelerators
A decoupled vector architecture co-processor.
Hwacha currently implements a non-standard RISC-V extension, using a vector architecture programming model.
Hwacha integrates with a Rocket or BOOM core using the RoCC (Rocket Custom Co-processor) interface.
See :ref:`Hwacha` for more information.
See :ref:`Generators/Hwacha:Hwacha` for more information.
**Gemmini**
A matrix-multiply accelerator targeting neural-networks
@@ -64,24 +64,24 @@ Tools
A hardware description library embedded in Scala.
Chisel is used to write RTL generators using meta-programming, by embedding hardware generation primitives in the Scala programming language.
The Chisel compiler elaborates the generator into a FIRRTL output.
See :ref:`Chisel` for more information.
See :ref:`Tools/Chisel:Chisel` for more information.
**FIRRTL**
An intermediate representation library for RTL description of digital designs.
FIRRTL is used as a formalized digital circuit representation between Chisel and Verilog.
FIRRTL enables digital circuits manipulation between Chisel elaboration and Verilog generation.
See :ref:`FIRRTL` for more information.
See :ref:`Tools/FIRRTL:FIRRTL` for more information.
**Barstools**
A collection of common FIRRTL transformations used to manipulate a digital circuit without changing the generator source RTL.
See :ref:`Barstools` for more information.
See :ref:`Tools/Barstools:Barstools` for more information.
**Dsptools**
A Chisel library for writing custom signal processing hardware, as well as integrating custom signal processing hardware into an SoC (especially a Rocket-based SoC).
**Dromajo**
A RV64GC emulator primarily used for co-simulation and was originally developed by Esperanto Technologies.
See :ref:`Dromajo` for more information.
See :ref:`Tools/Dromajo:Dromajo` for more information.
Toolchains
-------------------------------------------
@@ -109,12 +109,12 @@ Sims
**verilator (Verilator wrapper)**
Verilator is an open source Verilog simulator.
The ``verilator`` directory provides wrappers which construct Verilator-based simulators from relevant generated RTL, allowing for execution of test RISC-V programs on the simulator (including vcd waveform files).
See :ref:`Verilator (Open-Source)` for more information.
See :ref:`Simulation/Software-RTL-Simulation:Verilator (Open-Source)` for more information.
**vcs (VCS wrapper)**
VCS is a proprietary Verilog simulator.
Assuming the user has valid VCS licenses and installations, the ``vcs`` directory provides wrappers which construct VCS-based simulators from relevant generated RTL, allowing for execution of test RISC-V programs on the simulator (including vcd/vpd waveform files).
See :ref:`Synopsys VCS (License Required)` for more information.
See :ref:`Simulation/Software-RTL-Simulation:Synopsys VCS (License Required)` for more information.
**FireSim**
FireSim is an open-source FPGA-accelerated simulation platform, using Amazon Web Services (AWS) EC2 F1 instances on the public cloud.
@@ -122,7 +122,7 @@ Sims
To model I/O, FireSim includes synthesizeable and timing-accurate models for standard interfaces like DRAM, Ethernet, UART, and others.
The use of the elastic public cloud enable FireSim to scale simulations up to thousands of nodes.
In order to use FireSim, the repository must be cloned and executed on AWS instances.
See :ref:`FireSim` for more information.
See :ref:`Simulation/FPGA-Accelerated-Simulation:FireSim` for more information.
VLSI
-------------------------------------------
@@ -132,4 +132,4 @@ VLSI
The HAMMER flow provide automated scripts which generate relevant tool commands based on a higher level description of physical design constraints.
The Hammer flow also allows for re-use of process technology knowledge by enabling the construction of process-technology-specific plug-ins, which describe particular constraints relating to that process technology (obsolete standard cells, metal layer routing constraints, etc.).
The Hammer flow requires access to proprietary EDA tools and process technology libraries.
See :ref:`Core HAMMER` for more information.
See :ref:`VLSI/Hammer:Core HAMMER` for more information.

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

@@ -17,7 +17,7 @@ Configs
A *config* is a collection of multiple generator parameters being set to specific values.
Configs are additive, can override each other, and can be composed of other configs (sometimes referred to as config fragments).
The naming convention for an additive config or config fragment is ``With<YourConfigName>``, while the naming convention for a non-additive config will be ``<YourConfig>``.
Configs can take arguments which will in-turn set parameters in the design or reference other parameters in the design (see :ref:`Parameters`).
Configs can take arguments which will in-turn set parameters in the design or reference other parameters in the design (see :ref:`Chipyard-Basics/Configs-Parameters-Mixins:Parameters`).
This example shows a basic config fragment class that takes in zero arguments and instead uses hardcoded values to set the RTL design parameters.
In this example, ``MyAcceleratorConfig`` is a Scala case class that defines a set of variables that the generator can use when referencing the ``MyAcceleratorKey`` in the design.
@@ -121,7 +121,7 @@ This is shown in the ``Top`` class where things such as ``CanHavePeripherySerial
Additional References
---------------------------
Another description of traits/mixins and config fragments is given in :ref:`Keys, Traits, and Configs`.
Another description of traits/mixins and config fragments is given in :ref:`Customization/Keys-Traits-Configs:Keys, Traits, and Configs`.
Additionally, a brief explanation of some of these topics (with slightly different naming) is given in the following video: https://www.youtube.com/watch?v=Eko86PGEoDY.
.. Note:: Chipyard uses the name "config fragments" over "config mixins" to avoid confusion between a mixin applying to a config or to the system ``Top`` (even though both are technically Scala mixins).

2
docs/Chipyard-Basics/Initial-Repo-Setup.rst
View File

@@ -73,7 +73,7 @@ This depends on what you are planning to do with Chipyard.
* If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulating A Custom Project` and follow the instructions.
* If you intend to run a simulation of a custom Chipyard SoC Configuration, go to :ref:`Simulation/Software-RTL-Simulation:Simulating A Custom Project` and follow the instructions.
* If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions.

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

@@ -34,7 +34,7 @@ FESVR is a program that runs on the host CPU and can read/write arbitrary
parts of the target system memory using the Tethered Serial Interface (TSI).
FESVR uses TSI to load a baremetal executable or second-stage bootloader into
the SoC memory. In :ref:`Software RTL Simulation`, this will be the binary you
the SoC memory. In :ref:`Simulation/Software-RTL-Simulation:Software RTL Simulation`, this will be the binary you
pass to the simulator. Once it is finished loading the program, FESVR will
write to the software interrupt register for CPU 0, which will bring CPU 0
out of its WFI loop. Once it receives the interrupt, CPU 0 will write to

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

@@ -22,7 +22,7 @@ that writes zeros to the memory at a configured address.
We use ``TLHelper.makeClientNode`` to create a TileLink client node for us.
We then connect the client node to the memory system through the front bus (fbus).
For more info on creating TileLink client nodes, take a look at :ref:`Client Node`.
For more info on creating TileLink client nodes, take a look at :ref:`TileLink-Diplomacy-Reference/NodeTypes:Client Node`.
Once we've created our top-level module including the DMA widget, we can create a configuration for it as we did before.

4
docs/Customization/Firrtl-Transforms.rst
View File

@@ -5,7 +5,7 @@ Adding a Firrtl Transform
Similar to how LLVM IR passes can perform transformations and optimizations on software, FIRRTL transforms can
modify Chisel-elaborated RTL.
As mentioned in Section :ref:`firrtl`, transforms are modifications that happen on the FIRRTL IR that can modify a circuit.
As mentioned in Section :ref:`Tools/FIRRTL:firrtl`, transforms are modifications that happen on the FIRRTL IR that can modify a circuit.
Transforms are a powerful tool to take in the FIRRTL IR that is emitted from Chisel and run analysis or convert the circuit into a new form.
Where to add transforms
@@ -24,7 +24,7 @@ If you look inside of the `tools/barstools/tapeout/src/main/scala/transforms/Gen
you can see that FIRRTL is invoked twice, once for the "Top" and once for the "Harness". If you want to add transforms to just modify the DUT, you can add them to ``topTransforms``.
Otherwise, if you want to add transforms to just modify the test harness, you can add them to ``harnessTransforms``.
For more information on Barstools, please visit the :ref:`Barstools` section.
For more information on Barstools, please visit the :ref:`Tools/Barstools:Barstools` section.
Examples of transforms
----------------------

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

@@ -13,7 +13,7 @@ if you use the ``WithNMedCores`` or ``WithNSmallCores`` configurations, you can
configure 4 KiB direct-mapped caches for L1I and L1D.
If you only want to change the size or associativity, there are config
fragments for those too. See :ref:`Config Fragments` for how to add these to a custom ``Config``.
fragments for those too. See :ref:`Customization/Keys-Traits-Configs:Config Fragments` for how to add these to a custom ``Config``.
.. code-block:: scala

10
docs/Generators/IceNet.rst
View File

@@ -8,11 +8,11 @@ A diagram of IceNet's microarchitecture is shown below.
.. image:: ../_static/images/nic-design.png
There are four basic parts of the NIC: the :ref:`Controller`, which takes requests
from and sends responses to the CPU; the :ref:`Send Path`, which reads data from
memory and sends it out to the network; the :ref:`Receive Path`, which receives
There are four basic parts of the NIC: the :ref:`Generators/IceNet:Controller`, which takes requests
from and sends responses to the CPU; the :ref:`Generators/IceNet:Send Path`, which reads data from
memory and sends it out to the network; the :ref:`Generators/IceNet:Receive Path`, which receives
data from the network and writes it to memory; and, optionally,
the :ref:`Pause Handler`, which generates Ethernet pause frames for the purpose
the :ref:`Generators/IceNet:Pause Handler`, which generates Ethernet pause frames for the purpose
of flow control.
Controller
@@ -78,7 +78,7 @@ Configuration
To add IceNIC to your design, add ``HasPeripheryIceNIC`` to your lazy module
and ``HasPeripheryIceNICModuleImp`` to the module implementation. If you
are confused about the distinction between lazy module and module
implementation, refer to :ref:`Cake Pattern / Mixin`.
implementation, refer to :ref:`Chipyard-Basics/Configs-Parameters-Mixins:Cake Pattern / Mixin`.
Then add the ``WithIceNIC`` config fragment to your configuration. This will
define ``NICKey``, which IceNIC uses to determine its parameters. The config fragment

2
docs/Generators/Rocket-Chip.rst
View File

@@ -30,7 +30,7 @@ The tiles connect to the ``SystemBus``, which connect it to the L2 cache banks.
The L2 cache banks then connect to the ``MemoryBus``, which connects to the
DRAM controller through a TileLink to AXI converter.
To learn more about the memory hierarchy, see :ref:`Memory Hierarchy`.
To learn more about the memory hierarchy, see :ref:`Customization/Memory-Hierarchy:Memory Hierarchy`.
MMIO
----

10
docs/Generators/TestChipIP.rst
View File

@@ -2,9 +2,9 @@ Test Chip IP
============
Chipyard includes a Test Chip IP library which provides various hardware
widgets that may be useful when designing SoCs. This includes a :ref:`Serial Adapter`,
:ref:`Block Device Controller`, :ref:`TileLink SERDES`, :ref:`TileLink Switcher`,
:ref:`TileLink Ring Network`, and :ref:`UART Adapter`.
widgets that may be useful when designing SoCs. This includes a :ref:`Generators/TestChipIP:Serial Adapter`,
:ref:`Generators/TestChipIP:Block Device Controller`, :ref:`Generators/TestChipIP:TileLink SERDES`, :ref:`Generators/TestChipIP:TileLink Switcher`,
:ref:`Generators/TestChipIP:TileLink Ring Network`, and :ref:`Generators/TestChipIP:UART Adapter`.
Serial Adapter
--------------
@@ -14,7 +14,7 @@ processor. An instance of RISC-V frontend server running on the host CPU
can send commands to the serial adapter to read and write data from the memory
system. The frontend server uses this functionality to load the test program
into memory and to poll for completion of the program. More information on
this can be found in :ref:`Chipyard Boot Process`.
this can be found in :ref:`Customization/Boot-Process:Chipyard Boot Process`.
Block Device Controller
-----------------------
@@ -69,7 +69,7 @@ to the TLXbar provided by RocketChip, but uses ring networks internally rather
than crossbars. This can be useful for chips with very wide TileLink networks
(many cores and L2 banks) that can sacrifice cross-section bandwidth to relieve
wire routing congestion. Documentation on how to use the ring network can be
found in :ref:`The System Bus`. The implementation itself can be found
found in :ref:`Customization/Memory-Hierarchy:The System Bus`. The implementation itself can be found
`here <https://github.com/ucb-bar/testchipip/blob/master/src/main/scala/Ring.scala>`_,
and may serve as an example of how to implement your own TileLink network with
a different topology.

2
docs/Generators/index.rst
View File

@@ -4,7 +4,7 @@ Included RTL Generators
============================
A Generator can be thought of as a generalized RTL design, written using a mix of meta-programming and standard RTL.
This type of meta-programming is enabled by the Chisel hardware description language (see :ref:`Chisel`).
This type of meta-programming is enabled by the Chisel hardware description language (see :ref:`Tools/Chisel:Chisel`).
A standard RTL design is essentially just a single instance of a design coming from a generator.
However, by using meta-programming and parameter systems, generators can allow for integration of complex hardware designs in automated ways.
The following pages introduce the generators integrated with the Chipyard framework.

10
docs/TileLink-Diplomacy-Reference/NodeTypes.rst
View File

@@ -59,7 +59,7 @@ TileLink messages.
The ``edge`` object represents the edge of the Diplomacy graph. It contains
some useful helper functions which will be documented in
:ref:`TileLink Edge Object Methods`.
:ref:`TileLink-Diplomacy-Reference/EdgeFunctions:TileLink Edge Object Methods`.
Manager Node
------------
@@ -116,7 +116,7 @@ most MMIO peripherals should set it to.
The next six arguments start with ``support`` and determine the different
A channel message types that the manager can accept. The definitions of the
message types are explained in :ref:`TileLink Edge Object Methods`.
message types are explained in :ref:`TileLink-Diplomacy-Reference/EdgeFunctions:TileLink Edge Object Methods`.
The ``TransferSizes`` case class specifies the range of logical sizes (in bytes)
that the manager can accept for the particular message type. This is an inclusive
range and all logical sizes must be powers of two. So in this case, the manager
@@ -137,7 +137,7 @@ to handle TileLink requests, it is usually much easier to use a register node.
This type of node provides a ``regmap`` method that allows you to specify
control/status registers and automatically generates the logic to handle the
TileLink protocol. More information about how to use register nodes can be
found in :ref:`Register Router`.
found in :ref:`TileLink-Diplomacy-Reference/Register-Router:Register Router`.
Identity Node
-------------
@@ -176,7 +176,7 @@ If we want to connect the client and manager groups together, we can now do this
:end-before: DOC include end: MyClientManagerComplex
The meaning of the ``:=*`` operator is explained in more detail in the
:ref:`Diplomacy Connectors` section. In summary, it connects two nodes together
:ref:`TileLink-Diplomacy-Reference/Diplomacy-Connectors:Diplomacy Connectors` section. In summary, it connects two nodes together
using multiple edges. The edges in the identity node are assigned in order,
so in this case ``client1.node`` will eventually connect to ``manager1.node``
and ``client2.node`` will connect to ``manager2.node``.
@@ -192,7 +192,7 @@ produces the same number of outputs. However, unlike the identity node, the
adapter node does not simply pass the connections through unchanged.
It can change the logical and physical interfaces between input and output and
rewrite messages going through. RocketChip provides a library of adapters,
which are catalogued in :ref:`Diplomatic Widgets`.
which are catalogued in :ref:`TileLink-Diplomacy-Reference/Widgets:Diplomatic Widgets`.
You will rarely need to create an adapter node yourself, but the invocation is
as follows.

4
docs/TileLink-Diplomacy-Reference/Register-Router.rst
View File

@@ -32,7 +32,7 @@ The default value is 4 bytes. The ``concurrency`` argument is the size of the
internal queue for TileLink requests. By default, this value is 0, which means
there will be no queue. This value must be greater than 0 if you wish to
decoupled requests and responses for register accesses. This is discussed
in :ref:`Using Functions`.
in :ref:`TileLink-Diplomacy-Reference/Register-Router:Using Functions`.
The main way to interact with the node is to call the ``regmap`` method, which
takes a sequence of pairs. The first element of the pair is an offset from the
@@ -128,7 +128,7 @@ Register Routers for Other Protocols
One useful feature of the register router interface is that you can easily
change the protocol being used. For instance, in the first example in
:ref:`Basic Usage`, you could simply change the ``TLRegisterNode`` to
:ref:`TileLink-Diplomacy-Reference/Register-Router:Basic Usage`, you could simply change the ``TLRegisterNode`` to
and ``AXI4RegisterNode``.
.. literalinclude:: ../../generators/chipyard/src/main/scala/example/RegisterNodeExample.scala

16
docs/TileLink-Diplomacy-Reference/Widgets.rst
View File

@@ -81,7 +81,7 @@ The arguments for the five-argument constructor are
AXI4Buffer
----------
Similar to the :ref:`TLBuffer`, but for AXI4. It also takes ``BufferParams`` objects
Similar to the :ref:`TileLink-Diplomacy-Reference/Widgets:TLBuffer`, but for AXI4. It also takes ``BufferParams`` objects
as arguments.
**Arguments:**
@@ -200,7 +200,7 @@ transactions.
AXI4Fragmenter
--------------
The AXI4Fragmenter is similar to the :ref:`TLFragmenter`, except it can only
The AXI4Fragmenter is similar to the :ref:`TileLink-Diplomacy-Reference/Widgets:TLFragmenter`, except it can only
break multi-beat AXI4 transactions into single-beat transactions. This
effectively serves as an AXI4 to AXI4-Lite converter. The constructor for this
widget does not take any arguments.
@@ -237,7 +237,7 @@ you will want to use a TLSourceShrinker.
AXI4IdIndexer
-------------
The AXI4 equivalent of :ref:`TLSourceShrinker`. This limits the number of
The AXI4 equivalent of :ref:`TileLink-Diplomacy-Reference/Widgets:TLSourceShrinker`. This limits the number of
AWID/ARID bits in the slave AXI4 interface. Useful for connecting to external
or black box AXI4 ports.
@@ -257,7 +257,7 @@ or black box AXI4 ports.
The AXI4IdIndexer will create a ``user`` field on the slave interface, as it
stores the ID of the master requests in this field. If connecting to an AXI4
interface that doesn't have a ``user`` field, you'll need to use the :ref:`AXI4UserYanker`.
interface that doesn't have a ``user`` field, you'll need to use the :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker`.
TLWidthWidget
-------------
@@ -301,7 +301,7 @@ The possible values of ``policy`` are:
ordering guaranteed
- ``TLFIFOFixer.allVolatile`` - All managers that have a RegionType of
``VOLATILE``, ``PUT_EFFECTS``, or ``GET_EFFECTS`` will have ordering
guaranteed (see :ref:`Manager Node` for explanation of region types).
guaranteed (see :ref:`TileLink-Diplomacy-Reference/NodeTypes:Manager Node` for explanation of region types).
TLXbar and AXI4Xbar
-------------------
@@ -377,14 +377,14 @@ override the default arguments of the constructors for these widgets.
AXI4Fragmenter() :=
axi4master.node
You will need to add an :ref:`AXI4Deinterleaver` after the TLToAXI4 converter
You will need to add an :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4Deinterleaver` after the TLToAXI4 converter
because it cannot deal with interleaved read responses. The TLToAXI4 converter
also uses the AXI4 user field to store some information, so you will need an
:ref:`AXI4UserYanker` if you want to connect to an AXI4 port without user
:ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker` if you want to connect to an AXI4 port without user
fields.
Before you connect an AXI4 port to the AXI4ToTL widget, you will need to
add an :ref:`AXI4Fragmenter` and :ref:`AXI4UserYanker` because the converter cannot
add an :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4Fragmenter` and :ref:`TileLink-Diplomacy-Reference/Widgets:AXI4UserYanker` because the converter cannot
deal with multi-beat transactions or user fields.
TLROM

12
docs/Tools/Barstools.rst
View File

@@ -1,5 +1,3 @@
.. _barstools:
Barstools
===============================
@@ -25,15 +23,15 @@ An external module reference is a FIRRTL construct that enables a design to refe
A list of unique SRAM configurations is output to a ``.conf`` file by FIRRTL, which is used to map technology SRAMs.
Without this transform, FIRRTL will map all ``SeqMem`` s to flip-flop arrays with equivalent behavior, which may lead to a design that is difficult to route.
The ``.conf`` file is consumed by a tool called MacroCompiler, which is part of the :ref:`Barstools` scala package.
The ``.conf`` file is consumed by a tool called MacroCompiler, which is part of the :ref:`Tools/Barstools:Barstools` scala package.
MacroCompiler is also passed an ``.mdf`` file that describes the available list of technology SRAMs or the capabilities of the SRAM compiler, if one is provided by the foundry.
Typically a foundry SRAM compiler will be able to generate a set of different SRAMs collateral based on some requirements on size, aspect ratio, etc. (see :ref:`SRAM MDF Fields`).
Typically a foundry SRAM compiler will be able to generate a set of different SRAMs collateral based on some requirements on size, aspect ratio, etc. (see :ref:`Tools/Barstools:SRAM MDF Fields`).
Using a user-customizable cost function, MacroCompiler will select the SRAMs that are the best fit for each dimensionality in the ``.conf`` file.
This may include over provisioning (e.g. using a 64x1024 SRAM for a requested 60x1024, if the latter is not available) or arraying.
Arraying can be done in both width and depth, as well as to solve masking constraints.
For example, a 128x2048 array could be composed of four 64x1024 arrays, with two macros in parallel to create two 128x1024 virtual SRAMs which are combinationally muxed to add depth.
If this macro requires byte-granularity write masking, but no technology SRAMs support masking, then the tool may choose to use thirty-two 8x1024 arrays in a similar configuration.
For information on writing ``.mdf`` files, look at `MDF on github <https://github.com/ucb-bar/plsi-mdf>`__ and a brief description in :ref:`SRAM MDF Fields` section.
For information on writing ``.mdf`` files, look at `MDF on github <https://github.com/ucb-bar/plsi-mdf>`__ and a brief description in :ref:`Tools/Barstools:SRAM MDF Fields` section.
The output of MacroCompiler is a Verilog file containing modules that wrap the technology SRAMs into the specified interface names from the ``.conf``.
If the technology supports an SRAM compiler, then MacroCompiler will also emit HammerIR that can be passed to Hammer to run the compiler itself and generate design collateral.
@@ -105,7 +103,7 @@ This is necessary to facilitate post-synthesis and post-place-and-route simulati
Simulations after you the design goes through a VLSI flow will use the verilog netlist generated from the flow and will need an untouched test harness to drive it.
Separating these components into separate files makes this straightforward.
Without the separation the file that included the test harness would also redefine the DUT which is often disallowed in simulation tools.
To do this, there is a FIRRTL ``App`` in :ref:`Barstools` called ``GenerateTopAndHarness``, which runs the appropriate transforms to elaborate the modules separately.
To do this, there is a FIRRTL ``App`` in :ref:`Tools/Barstools:Barstools` called ``GenerateTopAndHarness``, which runs the appropriate transforms to elaborate the modules separately.
This also renames modules in the test harness so that any modules that are instantiated in both the test harness and the chip are uniquified.
.. Note:: For VLSI projects, this ``App`` is run instead of the normal FIRRTL ``App`` to elaborate Verilog.
@@ -133,5 +131,5 @@ This, unfortunately, breaks the process-agnostic RTL abstraction, so it is recom
The simplest way to do this is to have a config fragment that when included updates instantiates the IO cells and connects them in the test harness.
When simulating chip-specific designs, it is important to include the IO cells.
The IO cell behavioral models will often assert if they are connected incorrectly, which is a useful runtime check.
They also keep the IO interface at the chip and test harness boundary (see :ref:`Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route,
They also keep the IO interface at the chip and test harness boundary (see :ref:`Tools/Barstools:Separating the Top module from the TestHarness module`) consistent after synthesis and place-and-route,
which allows the RTL simulation test harness to be reused.

2
docs/Tools/Chisel-Testers.rst
View File

@@ -4,4 +4,4 @@ Chisel Testers
`Chisel Testers <https://github.com/freechipsproject/chisel-testers>`__ is a library for writing tests for Chisel designs.
It provides a Scala API for interacting with a DUT.
It can use multiple backends, including things such as Treadle and Verilator.
See :ref:`Treadle and FIRRTL Interpreter` and :ref:`sw-rtl-sim-intro` for more information on these simulation methods.
See :ref:`Tools/Treadle:Treadle and FIRRTL Interpreter` and :ref:`sw-rtl-sim-intro` for more information on these simulation methods.

2
docs/Tools/Chisel.rst
View File

@@ -13,7 +13,7 @@ The Chisel generator starts elaboration using the module and configuration class
This is where the Chisel "library functions" are called with the parameters given and Chisel tries to construct a circuit based on the Chisel code.
If a runtime error happens here, Chisel is stating that it cannot "build" your circuit due to "violations" between your code and the Chisel "library".
However, if that passes, the output of the generator gives you an FIRRTL file and other misc collateral!
See :ref:`FIRRTL` for more information on how to get a FIRRTL file to Verilog.
See :ref:`Tools/FIRRTL:FIRRTL` for more information on how to get a FIRRTL file to Verilog.
For an interactive tutorial on how to use Chisel and get started please visit the `Chisel Bootcamp <https://github.com/freechipsproject/chisel-bootcamp>`__.
Otherwise, for all things Chisel related including API documentation, news, etc, visit their `website <https://chisel-lang.org/>`__.

2
docs/Tools/Dromajo.rst
View File

@@ -19,4 +19,4 @@ An example of a divergence and Dromajo's printout is shown below.
Dromajo shows the divergence compared to simulation (PC, inst, inst-bits, write data, etc) and also provides the register state on failure.
It is useful to catch bugs that affect architectural state before a simulation hangs or crashes.
To use Dromajo with BOOM, refer to :ref:`Debugging RTL` section on Dromajo.
To use Dromajo with BOOM, refer to :ref:`Advanced-Concepts/Debugging-RTL:Debugging RTL` section on Dromajo.

7
docs/VLSI/Basic-Flow.rst
View File

@@ -40,7 +40,7 @@ Setting up the Hammer Configuration Files
--------------------------------------------
The first configuration file that needs to be set up is the Hammer environment configuration file ``env.yml``. In this file you need to set the paths to the EDA tools and license servers you will be using. You do not have to fill all the fields in this configuration file, you only need to fill in the paths for the tools that you will be using.
If you are working within a shared server farm environment with an LSF cluster setup (for example, the Berkeley Wireless Research Center), please note the additional possible environment configuration listed in the :ref:`Advanced Environment Setup` segment of this documentation page.
If you are working within a shared server farm environment with an LSF cluster setup (for example, the Berkeley Wireless Research Center), please note the additional possible environment configuration listed in the :ref:`VLSI/Basic-Flow:Advanced Environment Setup` segment of this documentation page.
Hammer relies on YAML-based configuration files. While these configuration can be consolidated within a single files (as is the case in the ASAP7 tutorial :ref:`tutorial` and the ``nangate45``
OpenRoad example), the generally suggested way to work with an arbitrary process technology or tools plugins would be to use three configuration files, matching the three Hammer concerns - tools, tech, and design.
@@ -63,7 +63,7 @@ We will do so by calling ``make buildfile`` with appropriate Chipyard configurat
As in the rest of the Chipyard flows, we specify our SoC configuration using the ``CONFIG`` make variable.
However, unlike the rest of the Chipyard flows, in the case of physical design we might be interested in working in a hierarchical fashion and therefore we would like to work on a single module.
Therefore, we can also specify a ``VLSI_TOP`` make variable with the same of a specific Verilog module (which should also match the name of the equivalent Chisel module) which we would like to work on.
The makefile will automatically call tools such as Barstools and the MacroCopmiler (:ref:`barstools`) in order to make the generated Verilog more VLSI friendly.
The makefile will automatically call tools such as Barstools and the MacroCopmiler (:ref:`Tools/Barstools:barstools`) in order to make the generated Verilog more VLSI friendly.
By default, the MacroCopmiler will attempt to map memories into the SRAM options within the Hammer technology plugin. However, if you are wokring with a new process technology are prefer to work with flipflop arrays, you can configure the MacroCompiler using the ``MACROCOMPILER_MODE`` make variable. For example, the ASAP7 process technology does not have associated SRAMs, and therefore the ASAP7 Hammer tutorial (:ref:`tutorial`) uses the ``MACROCOMPILER_MODE='--mode synflops'`` option (Note that synthesizing a design with only flipflops is very slow and will often may not meet constraints).
We call the ``make buildfile`` command while also specifying the name of the process technology we are working with (same ``tech_name`` for the configuration files and plugin name) and the configuration files we created. Note, in the ASAP7 tutorial ((:ref:`tutorial`)) these configuration files are merged into a single file called ``example-asap7.yml``.
@@ -116,6 +116,7 @@ Hence, if we want to monolitically place-and-route the entire SoC with the defau
In a more typical scenario of working on a single module, for example the Gemmini accelerator within the GemminiRocketConfig Chipyard SoC configuration,
.. code-block:: shell
vlsi.inputs.placement_constraints:
- path: "Gemmini"
type: toplevel
@@ -135,7 +136,7 @@ The relevant ``make`` command would then be
make par CONFIG=GemminiRocketConfig VLSI_TOP=Gemmini tech_name=tsmintel3 INPUT_CONFS="example-design.yml example-tools.yml example-tech.yml"
Note that the width and height specification can vary widely between different modulesi and level of the module hierarchy. Make sure to set sane width and height values.
Place-and-route generally requires more fine-grained input specifications regarding power nets, clock nets, pin assignments and floorplanning. While the template configuration files provide defaults for automatic tool defaults, these will usually result in very bad QoR, and therefore it is recommended to specify better-informed floorplans, pin assignments and power nets. For more information about cutomizing theses parameters, please refer to the :ref:`Customizing Your VLSI Flow in Hammer` sections or to the Hammer documentation.
Place-and-route generally requires more fine-grained input specifications regarding power nets, clock nets, pin assignments and floorplanning. While the template configuration files provide defaults for automatic tool defaults, these will usually result in very bad QoR, and therefore it is recommended to specify better-informed floorplans, pin assignments and power nets. For more information about cutomizing theses parameters, please refer to the :ref:`VLSI/Basic-Flow:Customizing Your VLSI Flow in Hammer` sections or to the Hammer documentation.
Additionally, some Hammer process technology plugins do not provide sufficient default values for requires settings such as power nets and pin assignments (for example, ASAP7). In those cases, these constraints will need to be specified manually in the top-level configuration yml files, as is the case in the ``example-asap7.yml`` configuration file.
Place-and-route tools are very sensitive to process technologes (significantly more sensitive than synthesis tools), and different process technologies may work only on specific tool versions. It is recommended to check what is the appropriate tool version for the specific process technology you are working with.

4
docs/VLSI/Building-A-Chip.rst
View File

@@ -10,7 +10,7 @@ Transforming the RTL
--------------------
Building a chip requires specializing the generic verilog emitted by FIRRTL to adhere to the constraints imposed by the technology used for fabrication.
This includes mapping Chisel memories to available technology macros such as SRAMs, mapping the input and output of your chip to connect to technology IO cells, see :ref:`Barstools`.
This includes mapping Chisel memories to available technology macros such as SRAMs, mapping the input and output of your chip to connect to technology IO cells, see :ref:`Tools/Barstools:Barstools`.
In addition to these required transformations, it may also be beneficial to transform the RTL to make it more amenable to hierarchical physical design easier.
This often includes modifying the logical hierarchy to match the physical hierarchy through grouping components together or flattening components into a single larger module.
@@ -49,6 +49,6 @@ Running the VLSI tool flow
--------------------------
For the full documentation on how to use the VLSI tool flow, see the `Hammer Documentation <https://hammer-vlsi.readthedocs.io/>`__.
For an example of how to use the VLSI in the context of Chipyard, see :ref:`ASAP7 Tutorial`.
For an example of how to use the VLSI in the context of Chipyard, see :ref:`VLSI/Tutorial:ASAP7 Tutorial`.

2
docs/VLSI/Tutorial.rst
View File

@@ -77,7 +77,7 @@ Pull the Hammer environment into the shell:
source $HAMMER_HOME/sourceme.sh
Building the Design
-------------------
--------------------
To elaborate the ``Sha3RocketConfig`` (Rocket Chip w/ the accelerator) and set up all prerequisites for the build system to push just the accelerator + hard macro through the flow:
.. code-block:: shell

1
docs/VLSI/index.rst
View File

@@ -10,5 +10,6 @@ In particular, we aim to support the Hammer physical design generator flow.
Building-A-Chip
Hammer
Basic-Flow
Tutorial
Advanced-Usage

3
docs/conf.py
View File

@@ -190,3 +190,6 @@ texinfo_documents = [
intersphinx_mapping = {'python' : ('https://docs.python.org/', None),
'boom' : ('https://docs.boom-core.org/en/latest/', None),
'firesim' : ('http://docs.fires.im/en/latest/', None) }
# resolve label conflict between documents
autosectionlabel_prefix_document = True

2
docs/index.rst
View File

@@ -11,7 +11,7 @@ Welcome to Chipyard's documentation!
Chipyard is a framework for designing and evaluating full-system hardware using agile teams.
It is composed of a collection of tools and libraries designed to provide an integration between open-source and commercial tools for the development of systems-on-chip.
.. IMPORTANT:: **New to Chipyard?** Jump to the :ref:`Initial Repository Setup` page for setup instructions.
.. IMPORTANT:: **New to Chipyard?** Jump to the :ref:`Chipyard-Basics/Initial-Repo-Setup:Initial Repository Setup` page for setup instructions.
Getting Help
------------