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

fix docs

Browse Source
This commit is contained in:
alonamid
2019-05-16 00:41:33 -07:00
parent f5c191871d
commit d091fe8b22
3 changed files with 61 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/Getting-Started/Configs-Parameters-Mixins.rst
View File

@@ -1,7 +1,7 @@
Configs, Parameters, Mix-ins, and Everything In Between
========================================================
A significant portion of generators in the ReBAR framework use the Rocket chip parameter system.
A significant portion of generators in the ReBAR 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:
@@ -13,15 +13,16 @@ It is important to note that a significant challenge with the Rocket parameter s
**Config**
A *Config* is a collection of multiple parameters being set to specific values.
A `Config` is a collection of multiple parameters being set to specific values.
Configs are additive, and can override each other.
A Config can be composed of other configs.
The naming convetion for an additive config is `With<YourConfig>`, while the naming convention for a non-additive config will be `<YourConfig>`.
The naming convetion for an additive config is ``With<YourConfig>``, while the naming convention for a non-additive config will be ``<YourConfig>``.
Configs can take arguments which will in-turn set parameters in the specific configs.
Example config:
..
.. code-block:: scala
class WithMyAcceleratorParams extends Config((site, here, up) => {
case MyAcceleratorKey =>
MyAcceleratorConfig(
@@ -35,7 +36,8 @@ Example config:
Example config which uses a higher level config:
..
.. code-block:: scala
class WithMyMoreComplexAcceleratorConfig extends Config((site, here, up) => {
case MyAcceleratorKey =>
MyAcceleratorConfig(
@@ -47,7 +49,8 @@ Example config which uses a higher level config:
Example of additive configs:
..
.. code-block:: scala
class SomeAdditiveConfig extends Config(
new WithMyMoreComplexAcceleratorConfig ++
new WithMyAcceleratorParams ++
@@ -60,7 +63,8 @@ The cake pattern is a scala programming pattern, which enable "mixing" of multip
Example of using the cake pattern to merge multiple system components into a single top-level design, extending a basic Rocket SoC:
..
.. code-block:: scala
class MySoC(implicit p: Parameters) extends RocketSubsystem
with CanHaveMisalignedMasterAXI4MemPort
with HasPeripheryBootROM
@@ -75,5 +79,5 @@ Example of using the cake pattern to merge multiple system components into a sin
**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 convetion for an additive mix-in is `Has<YourMixin>`.
The naming convetion for an additive mix-in is ``Has<YourMixin>``.

71
docs/Getting-Started/Running-A-Simulation.rst
View File

@@ -11,39 +11,50 @@ The ReBAR framework provides wrappers for two common software RTL simulators: th
Verilator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Verilator is an open-source RTL simulator. We run Verilator simulations from within the `sims/verisim` directory.
In order to construct the simulator with our custom design, we run the following command within the `sims/verisim` directory:
Verilator is an open-source RTL simulator. We run Verilator simulations from within the ``sims/verisim`` directory. Therefore, we will start by entering that directory:
.. code-block:: shell
cd sims/verisim
In order to construct the simulator with our custom design, we run the following command within the ``sims/verisim`` directory:
.. code-block:: shell
..
make TOP=<my_top_level_name> CONFIG=<my_config_name> SBT_PROJECT=<my_sbt_package_name> MODEL=<my_test_environment>
Where `<my_top_level_name>` is the class name of the top level design, `<my
The `make` command my have additional parameters (such as `CONFIG_PACKAGE` or `MODEL_PACKAGE`) depending on the complexity of the design and integration with multiple sub-project repositories in the sbt-based build system.
Where ``<my_top_level_name>`` is the class name of the top level design, ``<my_config_name>`` is the name of the class we create for our parameters configuration, ``<my_sbt_package_name>`` is the name of the sbt package the include both our top-level class and our config class, and ``<my_test_environment>`` is the name of the class which defines the test harness for our system.
The ``make`` command may have additional parameters (such as ``CONFIG_PACKAGE`` or ``MODEL_PACKAGE``) depending on the complexity of the design and integration with multiple sub-project repositories in the sbt-based build system.
Common configurations are package using a `SUB_PROJECT` make variable. There, in order to simulate a simple Rocket-based example system we can use:
Common configurations are package using a ``SUB_PROJECT`` make variable. There, 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 `sims/verisim` directory, we will find an executable file called `TODO`. We run this executable with out target RISC-V program as a command line argument. For example:
..
.. code-block:: shell
TODO
Alternatively, we can run a pre-packaged suite of RISC-V assembly tests, by adding the make target run-asm-tests. For example
..
.. code-block:: shell
make run-asm-tests TOP=<my_top_level_name> CONFIG=<my_config_name> SBT_PROJECT=<my_sbt_package_name> MODEL=<my_test_environment>
or
..
.. code-block:: shell
make run-asm-tests SUB_PROJECT=example
@@ -51,39 +62,51 @@ or
VCS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
VCS is a proprietry RTL simulator. This guide assumes that the VCS installation is found on our PATH. We run VCS simulations from within the `sims/vsim` directory.
In order to construct the simulator with our custom design, we run the following command within the `sims/vsim` directory:
VCS is a proprietry RTL simulator. This guide assumes that the VCS installation is found on our PATH. We run VCS simulations from within the ``sims/vsim`` directory. Therefore, we will start by entering the directory:
.. code-block:: shell
cd sims/vsim
In order to construct the simulator with our custom design, we run the following command within the ``sims/vsim`` directory:
.. code-block:: shell
..
make TOP=<my_top_level_name> CONFIG=<my_config_name> SBT_PROJECT=<my_sbt_package_name> MODEL=<my_test_environment>
Where `<my_top_level_name>` is the class name of the top level design, `<my
The `make` command my have additional parameters (such as `CONFIG_PACKAGE` or `MODEL_PACKAGE`) depending on the complexity of the design and integration with multiple sub-project repositories in the sbt-based build system.
Where ``<my_top_level_name>`` is the class name of the top level design, ``<my_config_name>`` is the name of the class we create for our parameters configuration, ``<my_sbt_package_name>`` is the name of the sbt package the include both our top-level class and our config class, and ``<my_test_environment>`` is the name of the class which defines the test harness for our system.
The ``make`` command my have additional parameters (such as ``CONFIG_PACKAGE`` or ``MODEL_PACKAGE``) depending on the complexity of the design and integration with multiple sub-project repositories in the sbt-based build system.
Common configurations are package using a `SUB_PROJECT` make variable. There, in order to simulate a simple Rocket-based example system we can use:
Common configurations are package using a ``SUB_PROJECT`` make variable. There, 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 `sims/vsim` directory, we will find an executable file called `TODO`. We run this executable with out target RISC-V program as a command line argument. For example:
Once the simulator has been constructed, we would like to run RISC-V programs on it. In the ``sims/vsim`` directory, we will find an executable file called ``TODO``. We run this executable with out target RISC-V program as a command line argument. For example:
.. code-block:: shell
..
TODO
Alternatively, we can run a pre-packaged suite of RISC-V assembly tests, by adding the make target run-asm-tests. For example
..
.. code-block:: shell
make run-asm-tests TOP=<my_top_level_name> CONFIG=<my_config_name> SBT_PROJECT=<my_sbt_package_name> MODEL=<my_test_environment>
or
..
.. code-block:: shell
make run-asm-tests SUB_PROJECT=example
@@ -94,7 +117,7 @@ FireSim enables simulations at 1000x-100000x the speed of standard software simu
To run an FPGA-accelerated simulation using FireSim, a we need to clone the ReBAR repository (or our fork of the ReBAR repository) to an AWS EC2, and follow the setup instructions specificied 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.
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

4
docs/Getting-Started/index.rst
View File

@@ -1,6 +1,6 @@
.. _ReBAR Basics:
.. _Getting Started:
ReBAR Basics
Getting Started
================================
These guides will walk you through the basics of the ReBAR framework: