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

docs reorg

Browse Source
This commit is contained in:
alonamid
2019-07-25 01:20:38 -07:00
parent fe45d94974
commit aec0fb73c4
18 changed files with 145 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/Chipyard-Basics/Building-A-Chip.rst Normal file
View File

@@ -0,0 +1,3 @@
Building A Chip
==============================
TODO

110
docs/Chipyard-Basics/Chipyard-Components.rst Normal file
View File

@@ -0,0 +1,110 @@
Chipyard Components
===============================
Generators
-------------------------------------------
The Chipyard Framework currently consists of the following RTL generators:
Processor Cores
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Rocket**
An in-order RISC-V core.
See :ref:`Rocket` 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.
Accelerators
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**Hwacha**
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.
System Components:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
**icenet**
A Network Interface Controller (NIC) designed to achieve up to 200 Gbps.
**sifive-blocks**
System components implemented by SiFive and used by SiFive projects, designed to be integrated with the Rocket Chip generator.
These system and peripheral components include UART, SPI, JTAG, I2C, PWM, and other peripheral and interface devices.
**AWL (Analog Widget Library)**
Digital components required for integration with high speed serial links.
**testchipip**
A collection of utilities used for testing chips and interfacing them with larger test environments.
.. Fixed Function Accelerators:
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TBD
Tools
-------------------------------------------
**Chisel**
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.
**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.
**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.
Toolchains
-------------------------------------------
**riscv-tools**
A collection of software toolchains used to develop and execute software on the RISC-V ISA.
The include compiler and assembler toolchains, functional ISA simulator (spike), the Berkeley Boot Loader (BBL) and proxy kernel.
The riscv-tools repository was previously required to run any RISC-V software, however, many of the riscv-tools components have since been upstreamed to their respective open-source projects (Linux, GNU, etc.).
Nevertheless, for consistent versioning, as well as software design flexibility for custom hardware, we include the riscv-tools repository and installation in the Chipyard framework.
**esp-tools**
A fork of riscv-tools, designed to work with the Hwacha non-standard RISC-V extension.
This fork can also be used as an example demonstrating how to add additional RoCC accelerators to the ISA-level simulation (Spike) and the higher-level software toolchain (GNU binutils, riscv-opcodes, etc.)
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` 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:`VCS` 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.
FireSim automatically transforms and instruments open-hardware designs into fast (10s-100s MHz), deterministic, FPGA-based simulators that enable productive pre-silicon verification and performance validation.
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.
VLSI
-------------------------------------------
**HAMMER**
HAMMER is a VLSI flow designed to provide a layer of abstraction between general physical design concepts to vendor-specific EDA tool commands.
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:`HAMMER` for more information.

133
docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst Normal file
View File

@@ -0,0 +1,133 @@
SoC Generator Config Mix-ins:
==============================
Rocket Chip
-----------------------
+ System-on-Chip
- HasTiles
- HasClockDomainCrossing
- HasResetVectorWire
- HasNoiseMakerIO
+ Basic Core
- HasRocketTiles
- HasRocketCoreParameters
- HasCoreIO
+ Branch Prediction
- HasBtbParameters
+ Additional Compute
- HasFPUCtrlSigs
- HasFPUParameters
- HasLazyRoCC
- HasFpuOpt
+ Memory System
- HasRegMap
- HasCoreMemOp
- HasHellaCache
- HasL1ICacheParameters
- HasICacheFrontendModule
- HasAXI4ControlRegMap
- HasTLControlRegMap
- HasTLBusParams
- HasTLXbarPhy
+ Interrupts
- HasInterruptSources
- HasExtInterrupts
- HasAsyncExtInterrupts
- HasSyncExtInterrupts
+ Periphery
- HasPeripheryDebug
- HasPeripheryBootROM
- HasBuiltInDeviceParams
BOOM
-----------------------
+ Basic Core
- HasBoomTiles
- HasBoomCoreParameters
- HasBoomCoreIO
- HasBoomUOP
- HasRegisterFileIO
+ Branch Prediction
- HasGShareParameters
- HasBoomBTBParameters
+ Memory System
- HasL1ICacheBankedParameters
- HasBoomICacheFrontend
- HasBoomHellaCache
SiFive Blocks
-----------------------
+ Peripherals
- HasPeripheryGPIO
- HasPeripheryI2C
- HasPeripheryMockAON
- HasPeripheryPWM
- HasPeripherySPI
- HasSPIProtocol
- HasSPIEndian
- HasSPILength
- HasSPICSMode
- HasPeripherySPIFlash
- HasPeripheryUART
testchipip
-----------------------
+ Peripherals
- HasPeripheryBlockDevice
- HasPeripherySerial
- HasNoDebug
Icenet
-----------------------
+ Periphery Network Interface Controller
- HasPeripheryIceNIC
AWL
-----------------------
+ IO
- HasEncoding8b10b
- HasTLBidirectionalPacketizer
- HasTLController
- HasGenericTransceiverSubsystem
+ Debug/Testing
- HasBertDebug
- HasPatternMemDebug
- HasBitStufferDebug4Modes
- HasBitReversalDebug

100
docs/Chipyard-Basics/Configs-Parameters-Mixins.rst Normal file
View File

@@ -0,0 +1,100 @@
Configs, Parameters, Mix-ins, and Everything In Between
========================================================
A significant portion of generators in the Chipyard framework use the Rocket Chip parameter system.
This parameter system enables for the flexible configuration of the SoC without invasive RTL changes.
In order to use the parameter system correctly, we will use several terms and conventions:
Parameters
--------------------
TODO: Need to explain up, site, field, and other stuff from Henry's thesis.
It is important to note that a significant challenge with the Rocket parameter system is being able to identify the correct parameter to use, and the impact that parameter has on the overall system.
We are still investigating methods to facilitate parameter exploration and discovery.
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.
The naming convention for an additive Config 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`).
:numref:`basic-config-example` shows a basic additive Config 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.
.. _basic-config-example:
.. code-block:: scala
class WithMyAcceleratorParams extends Config((site, here, up) => {
case BusWidthBits => 128
case MyAcceleratorKey =>
MyAcceleratorConfig(
rows = 2,
rowBits = 64,
columns = 16,
hartId = 1,
someLength = 256)
})
This next example (:numref:`complex-config-example`) shows a "higher-level" additive Config that uses prior parameters that were set to derive other parameters.
.. _complex-config-example:
.. code-block:: scala
class WithMyMoreComplexAcceleratorConfig extends Config((site, here, up) => {
case BusWidthBits => 128
case MyAcceleratorKey =>
MyAcceleratorConfig(
Rows = 2,
rowBits = site(SystemBusKey).beatBits,
hartId = up(RocketTilesKey, site).length)
})
:numref:`top-level-config` shows a non-additive Config that combines the prior two additive Configs using ``++``.
The additive Configs are applied from the right to left in the list (or bottom to top in the example).
Thus, the order of the parameters being set will first start with the ``DefaultExampleConfig``, then ``WithMyAcceleratorParams``, then ``WithMyMoreComplexAcceleratorConfig``.
.. _top-level-config:
.. code-block:: scala
class SomeAdditiveConfig extends Config(
new WithMyMoreComplexAcceleratorConfig ++
new WithMyAcceleratorParams ++
new DefaultExampleConfig
)
Cake Pattern
-------------------------
A cake pattern is a Scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes referred to as dependency injection).
It is used in the Rocket Chip SoC library and Chipyard framework in merging multiple system components and IO interfaces into a large system component.
:numref:`cake-example` shows a Rocket Chip based SoC that merges multiple system components (BootROM, UART, etc) into a single top-level design.
.. _cake-example:
.. code-block:: scala
class MySoC(implicit p: Parameters) extends RocketSubsystem
with CanHaveMisalignedMasterAXI4MemPort
with HasPeripheryBootROM
with HasNoDebug
with HasPeripherySerial
with HasPeripheryUART
with HasPeripheryIceNIC
{
//Additional top-level specific instantiations or wiring
}
Mix-in
---------------------------
A mix-in is a Scala trait, which sets parameters for specific system components, as well as enabling instantiation and wiring of the relevant system components to system buses.
The naming convention for an additive mix-in is ``Has<YourMixin>``.
This is show in :numref:`cake-example` where things such as ``HasPeripherySerial`` connect a RTL component to a bus and expose signals to the top-level.
Additional References
---------------------------
A brief explanation of some of these topics is given in the following video: https://www.youtube.com/watch?v=Eko86PGEoDY.

25
docs/Chipyard-Basics/Development-Ecosystem.rst Normal file
View File

@@ -0,0 +1,25 @@
Development Ecosystem
===============================
Chipyard Approach
-------------------------------------------
The trend towards agile hardware design and evaluation provides an ecosystem of debugging and implementation tools, that make it easier for computer architecture researchers to develop novel concepts.
Chipyard hopes to build on this prior work in order to create a singular location to which multiple projects within the `Berkeley Architecture Research <https://bar.eecs.berkeley.edu/index.html>`__ can coexist and be used together.
Chipyard aims to be the "one-stop shop" for creating and testing your own unique System on a Chip (SoC).
Chisel/FIRRTL
-------------------------------------------
One of the tools to help create new RTL designs quickly is the `Chisel Hardware Construction Language <https://chisel.eecs.berkeley.edu/>`__ and the `FIRRTL Compiler <https://freechipsproject.github.io/firrtl/>`__.
Chisel is an embedded language within Scala that provides a set of libraries to help hardware designers create highly parameterizable RTL.
FIRRTL on the other hand is a compiler for hardware which allows the user to run FIRRTL passes that can do dead code elimination, circuit analysis, connectivity checks, and much more!
These two tools in combination allow quick design space exploration and development of new RTL.
Generators
-------------------------------------------
Within this repository, all of the Chisel RTL is written as generators.
Generators are parametrized programs designed to generate RTL code based on configuration specifications.
Generators can be used to generate Systems-on-Chip (SoCs) using a collection of system components organized in unique generator projects.
Generators allow you to create a family of SoC designs instead of a single instance of a design!

33
docs/Chipyard-Basics/Initial-Repo-Setup.rst Normal file
View File

@@ -0,0 +1,33 @@
Initial Repository Setup
========================================================
Checking out the sources
------------------------
After cloning this repo, you will need to initialize all of the submodules.
.. code-block:: shell
git clone https://github.com/ucb-bar/chipyard.git
cd chipyard
./scripts/init-submodules-no-riscv-tools.sh
Building a Toolchain
------------------------
The `toolchains` directory contains toolchains that include a cross-compiler toolchain, frontend server, and proxy kernel, which you will need in order to compile code to RISC-V instructions and run them on your design.
Currently there are two toolchains, one for normal RISC-V programs, and another for Hwacha (``esp-tools``).
There are detailed instructions at https://github.com/riscv/riscv-tools to install the ``riscv-tools`` toolchain, however, the instructions are similar for the Hwacha ``esp-tools`` toolchain.
But to get a basic installation, just the following steps are necessary.
.. code-block:: shell
./scripts/build-toolchains.sh riscv # for a normal risc-v toolchain
# OR
./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions
Once the script is run, a ``env.sh`` file is emitted at sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables.
You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables.
These variables need to be set for the make system to work properly.

106
docs/Chipyard-Basics/Running-A-Simulation.rst Normal file
View File

@@ -0,0 +1,106 @@
Running A Simulation
========================================================
Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements.
In the majority of cases during a digital design development process, simple software RTL simulation is needed.
When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution.
Software RTL Simulation
------------------------
The Chipyard framework provides wrappers for two common software RTL simulators:
the open-source Verilator simulator and the proprietary VCS simulator.
For more information on either of these simulators, please refer to :ref:`Verilator` or :ref:`VCS`.
The following instructions assume at least one of these simulators is installed.
Verilator/VCS Flows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Verilator is an open-source RTL simulator.
We run Verilator simulations from within the ``sims/verilator`` directory which provides the necessary ``Makefile`` to both install and run Verilator simulations.
On the other hand, VCS is a proprietary RTL simulator.
We run VCS simulations from within the ``sims/vcs`` directory.
Assuming VCS is already installed on the machine running simulations (and is found on our ``PATH``), then this guide is the same for both Verilator and VCS.
First, we will start by entering the Verilator or VCS directory:
.. code-block:: shell
# Enter Verilator directory
cd sims/verilator
# OR
# Enter VCS directory
cd sims/vcs
In order to construct the simulator with our custom design, we run the following command within the simulator directory:
.. code-block:: shell
make SBT_PROJECT=... MODEL=... VLOG_MODEL=... MODEL_PACKAGE=... CONFIG=... CONFIG_PACKAGE=... GENERATOR_PACKAGE=... TB=... TOP=...
Each of these make variables correspond to a particular part of the design/codebase and are needed so that the make system can correctly build and make a RTL simulation.
The ``SBT_PROJECT`` is the ``build.sbt`` project that holds all of the source files and that will be run during the RTL build.
The ``MODEL`` and ``VLOG_MODEL`` are the top-level class names of the design.
Normally, these are the same, but in some cases these can differ (if the Chisel class differs than what is emitted in the Verilog).
The ``MODEL_PACKAGE`` is the Scala package (in the Scala code that says ``package ...``) that holds the ``MODEL`` class.
The ``CONFIG`` is the name of the class used for the parameter Config while the ``CONFIG_PACKAGE`` is the Scala package it resides in.
The ``GENERATOR_PACKAGE`` is the Scala package that holds the Generator class that elaborates the design.
The ``TB`` is the name of the Verilog wrapper that connects the ``TestHarness`` to VCS/Verilator for simulation.
Finally, the ``TOP`` variable is used to distinguish between the top-level of the design and the ``TestHarness`` in our system.
For example, in the normal case, the ``MODEL`` variable specifies the ``TestHarness`` as the top-level of the design.
However, the true top-level design, the SoC being simulated, is pointed to by the ``TOP`` variable.
This separation allows the infrastructure to separate files based on the harness or the SoC top level.
Common configurations of all these variables are packaged using a ``SUB_PROJECT`` make variable.
Therefore, in order to simulate a simple Rocket-based example system we can use:
.. code-block:: shell
make SUB_PROJECT=example
Alternatively, if we would like to simulate a simple BOOM-based example system we can use:
.. code-block:: shell
make SUB_PROJECT=exampleboom
Once the simulator has been constructed, we would like to run RISC-V programs on it.
In the simulation directory, we will find an executable file called ``<...>-<package>-<config>``.
We run this executable with our target RISC-V program as a command line argument in one of two ways.
One, we can directly call the simulator binary or use make to run the binary for us with extra simulation flags.
For example:
.. code-block:: shell
# directly calling the simulation binary
./<...>-<package>-<config> my_program_binary
# using make to do it
make SUB_PROJECT=example BINARY=my_program_binary run-binary
Alternatively, we can run a pre-packaged suite of RISC-V assembly or benchmark tests, by adding the make target ``run-asm-tests`` or ``run-bmark-tests``.
For example:
.. code-block:: shell
make SUB_PROJECT=example run-asm-tests
make SUB_PROJECT=example run-bmark-tests
Note: You need to specify all the make variables once again to match what the build gave to run the assembly tests or the benchmarks or the binaries if you are using the make option.
Finally, in the ``generated-src/<...>-<package>-<config>/`` directory resides all of the collateral and Verilog source files for the build/simulation.
Specifically, the SoC top-level (``TOP``) Verilog file is denoted with ``*.top.v`` while the ``TestHarness`` file is denoted with ``*.harness.v``.
FPGA Accelerated Simulation
---------------------------
FireSim enables simulations at 1000x-100000x the speed of standard software simulation.
This is enabled using FPGA-acceleration on F1 instances of the AWS (Amazon Web Services) public cloud.
Therefore FireSim simulation requires to be set-up on the AWS public cloud rather than on our local development machine.
To run an FPGA-accelerated simulation using FireSim, a we need to clone the Chipyard repository (or our fork of the Chipyard repository) to an AWS EC2, and follow the setup instructions specified in the FireSim Initial Setup documentation page.
After setting up the FireSim environment, we now need to generate a FireSim simulation around our selected digital design.
We will work from within the ``sims/firesim`` directory.
TODO: Continue from here

24
docs/Chipyard-Basics/index.rst Normal file
View File

@@ -0,0 +1,24 @@
Chipyard Basics
================================
These guides will walk you through the basics of the Chipyard framework:
- First, we will go over the components of the framework.
- Next, we will go over the different configurations available.
- Then, we will go over initial framework setup.
- Finally, we will briefly walk through what you can do with the Chipyard tools.
Hit next to get started!
.. toctree::
:maxdepth: 2
:caption: Chipyard Basics:
Chipyard-Components
Configs-Parameters-Mixins
Initial-Repo-Setup
Running-A-Simulation
Building-A-Chip