From 7e1365f142c3640ad9e5c2754971733bf0927f69 Mon Sep 17 00:00:00 2001 From: alonamid Date: Fri, 17 May 2019 14:33:58 -0700 Subject: [PATCH] more docs skeleton --- docs/Generators/BOOM.rst | 10 +++++++++ docs/Generators/Rocket.rst | 3 +++ docs/Generators/index.rst | 13 ++++++++++++ docs/Getting-Started/Running-A-Simulation.rst | 4 ++-- docs/Simulation/Commercial-Simulators.rst | 2 +- docs/Simulation/FPGA-Based-Simulators.rst | 6 +++--- docs/Simulation/Open-Source-Simulators.rst | 2 +- docs/Simulation/index.rst | 13 ++++++++++++ docs/Tools/Barstools.rst | 3 +++ docs/Tools/Chisel.rst | 3 +++ docs/Tools/FIRRTL.rst | 3 +++ docs/Tools/index.rst | 13 ++++++++++++ docs/VLSI/index.rst | 8 +++++++ docs/conf.py | 4 +++- docs/index.rst | 21 ++++++++++++++++++- 15 files changed, 99 insertions(+), 9 deletions(-) create mode 100644 docs/Generators/BOOM.rst create mode 100644 docs/Generators/Rocket.rst create mode 100644 docs/Generators/index.rst create mode 100644 docs/Simulation/index.rst create mode 100644 docs/Tools/Barstools.rst create mode 100644 docs/Tools/Chisel.rst create mode 100644 docs/Tools/FIRRTL.rst create mode 100644 docs/Tools/index.rst create mode 100644 docs/VLSI/index.rst diff --git a/docs/Generators/BOOM.rst b/docs/Generators/BOOM.rst new file mode 100644 index 00000000..f0cac535 --- /dev/null +++ b/docs/Generators/BOOM.rst @@ -0,0 +1,10 @@ +Berkeley Out-of-Order Machine (BOOM) +============================================== + +The Berkeley Out-of-Order Machine (BOOM) is a synthesizable and parameterizable open source RV64GC RISC-V core written in the Chisel hardware construction language. + +BOOM is heavily inspired by the MIPS R10k and the Alpha 21264 outoforder processors. Like the R10k and the 21264, BOOM is a unified physical register file design (also known as “explicit register renaming”). + +Conceptually, BOOM is broken up into 10 stages: Fetch, Decode, Register Rename, Dispatch, Issue, Register Read, Execute, Memory, Writeback and Commit. However, many of those stages are combined in the current implementation, yielding seven stages: Fetch, Decode/Rename, Rename/Dispatch, Issue/RegisterRead, Execute, Memory and Writeback (Commit occurs asynchronously, so it is not counted as part of the “pipeline”). + +Additional information about the BOOM micro-architecture can be found in the `BOOM documentation pages __`. diff --git a/docs/Generators/Rocket.rst b/docs/Generators/Rocket.rst new file mode 100644 index 00000000..06bf26eb --- /dev/null +++ b/docs/Generators/Rocket.rst @@ -0,0 +1,3 @@ +Rocket +==================================== +TODO: Basic rocket introduction diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst new file mode 100644 index 00000000..7aa22141 --- /dev/null +++ b/docs/Generators/index.rst @@ -0,0 +1,13 @@ +Generators +============================ +Generator can be thought of as generalized RTL designs, written using a mix of meta-programming and standard RTL. +This type of meta-programming is enabled by the Chisel hardware description framework embedded in Scala. +A standard RTL design is esentially a degenerate form of 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 ReBAR framework. + +.. toctree:: + :maxdepth: 2 + :caption: Generators: + + Rocket + BOOM + diff --git a/docs/Getting-Started/Running-A-Simulation.rst b/docs/Getting-Started/Running-A-Simulation.rst index c9f48689..a86eb7e8 100644 --- a/docs/Getting-Started/Running-A-Simulation.rst +++ b/docs/Getting-Started/Running-A-Simulation.rst @@ -43,7 +43,7 @@ Once the simulator has been constructed, we would like to run RISC-V programs on .. code-block:: shell - TODO + ./simulator-- my_program_binary Alternatively, we can run a pre-packaged suite of RISC-V assembly tests, by adding the make target run-asm-tests. For example @@ -95,7 +95,7 @@ Once the simulator has been constructed, we would like to run RISC-V programs on .. code-block:: shell - TODO + ./simulator-- my_program_binary Alternatively, we can run a pre-packaged suite of RISC-V assembly tests, by adding the make target run-asm-tests. For example diff --git a/docs/Simulation/Commercial-Simulators.rst b/docs/Simulation/Commercial-Simulators.rst index e107d703..27fa5271 100644 --- a/docs/Simulation/Commercial-Simulators.rst +++ b/docs/Simulation/Commercial-Simulators.rst @@ -1,4 +1,4 @@ -Commericial Simulators +Commericial Software RTL Simulators ============================== The ReBAR framework currently supports only the VCS commerical simulator diff --git a/docs/Simulation/FPGA-Based-Simulators.rst b/docs/Simulation/FPGA-Based-Simulators.rst index fbacafa4..37bc3b16 100644 --- a/docs/Simulation/FPGA-Based-Simulators.rst +++ b/docs/Simulation/FPGA-Based-Simulators.rst @@ -4,10 +4,10 @@ FPGA-Based Simulators FireSim ----------------------- FireSim is an open-source cycle-accurate FPGA-accelerated full-system hardware simulation platform that runs on cloud FPGAs (Amazon EC2 F1). -FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators. FireSim also provide additional device models to allow full-system simulation, including memory models and network models. +FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than software RTL simulators. FireSim also provides additional device models to allow full-system simulation, including memory models and network models. FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances on the public cloud. In order to simulate your ReBAR design using FireSim, you should follow the following steps: -Follow the initial EC2 setup instructions as detailed in the FireSim documentatino . Then clone your full ReBAR repository onto your Amazon EC2 FireSim manager instance. +Follow the initial EC2 setup instructions as detailed in the `FireSim documentation `__ .. Then clone your full ReBAR repository onto your Amazon EC2 FireSim manager instance. -Enter the ``sims/FireSim`` directory, and follow the FireSim instructions for running a simulation +Enter the ``sims/FireSim`` directory, and follow the FireSim instructions for `running a simulation `__. diff --git a/docs/Simulation/Open-Source-Simulators.rst b/docs/Simulation/Open-Source-Simulators.rst index 2b8e1f4e..87edc5ef 100644 --- a/docs/Simulation/Open-Source-Simulators.rst +++ b/docs/Simulation/Open-Source-Simulators.rst @@ -1,4 +1,4 @@ -Open Source Simulators +Open Source Software RTL Simulators ============================== Verilator diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst new file mode 100644 index 00000000..c5ee90a5 --- /dev/null +++ b/docs/Simulation/index.rst @@ -0,0 +1,13 @@ +Simulators +======================= + +ReBAR provides support and intergration for multiple simulation flows, for various user levels and requirments. +In the majority of cases during a digital design development process, simple software RTL. When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution. The following pages provide detailed information about the simulation possibilities within the ReBAR framework. + +.. toctree:: + :maxdepth: 2 + :caption: Simulators: + + Open-Source-Simulators + Commercial-Simulators + FPGA-Based-Simulators diff --git a/docs/Tools/Barstools.rst b/docs/Tools/Barstools.rst new file mode 100644 index 00000000..137d95a7 --- /dev/null +++ b/docs/Tools/Barstools.rst @@ -0,0 +1,3 @@ +Barstools +=============================== +Barstools is a collection of useful FIRRTL transformations diff --git a/docs/Tools/Chisel.rst b/docs/Tools/Chisel.rst new file mode 100644 index 00000000..1b0c37ce --- /dev/null +++ b/docs/Tools/Chisel.rst @@ -0,0 +1,3 @@ +Chisel +=========================== +TODO: Chisel intro and pointer to chisel bootcamp diff --git a/docs/Tools/FIRRTL.rst b/docs/Tools/FIRRTL.rst new file mode 100644 index 00000000..ab5df854 --- /dev/null +++ b/docs/Tools/FIRRTL.rst @@ -0,0 +1,3 @@ +FIRRTL +================================ + diff --git a/docs/Tools/index.rst b/docs/Tools/index.rst new file mode 100644 index 00000000..6b3ad2da --- /dev/null +++ b/docs/Tools/index.rst @@ -0,0 +1,13 @@ +Tools +============================== +The ReBAR framework relays heavily on a set of scala-based tools. While the framework attempts to hide the complexities of these tools, the following pages will introduce them, and how we can use them in order to generate flexible designs + + +.. toctree:: + :maxdepth: 2 + :caption: Tools: + + Chisel + FIRRTL + Barstools + diff --git a/docs/VLSI/index.rst b/docs/VLSI/index.rst new file mode 100644 index 00000000..5f680b4d --- /dev/null +++ b/docs/VLSI/index.rst @@ -0,0 +1,8 @@ +VLSI Production +================================ +The ReBAR framework aim to provide wrappers to a general VLSI flow. +In particular, we aim to support the HAMMER flow. + +.. toctree:: + :maxdepth: 2 + :caption: VLSI Production: diff --git a/docs/conf.py b/docs/conf.py index 64757ea1..bdddec6c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -181,4 +181,6 @@ texinfo_documents = [ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +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) } diff --git a/docs/index.rst b/docs/index.rst index 4123f632..a696f691 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,7 +28,6 @@ The documentation outline should look like this Simulation: - Simulation/Open-Source-Simulators/index Simulation/Commercial-Simulators/index Simulation/FPGA-Based-Simulation/index @@ -47,6 +46,26 @@ The documentation outline should look like this Getting-Started/index + :maxdepth: 3 + :caption: Simulation: + :numbered: + Simulation/index + + :maxdepth: 3 + :caption: Generators: + :numbered: + Generators/index + + :maxdepth: 3 + :caption: Tools: + :numbered: + Tools/index + + :maxdepth: 3 + :caption: VLSI Production: + :numbered: + VLSI/index + Indices and tables ==================