From 3b14ac8706d6a0abe776123e612afb40f7b0558f Mon Sep 17 00:00:00 2001 From: Abraham Gonzalez Date: Mon, 27 May 2019 17:11:10 -0700 Subject: [PATCH] minor fixes to links | misc cleanup --- docs/Generators/BOOM.rst | 2 +- .../Adding-An-Accelerator-Tutorial.rst | 20 +++++++++++++++++-- docs/Simulation/Commercial-Simulators.rst | 2 ++ docs/Simulation/Open-Source-Simulators.rst | 2 ++ docs/Tools/Chisel.rst | 2 +- docs/conf.py | 3 ++- docs/index.rst | 2 +- 7 files changed, 27 insertions(+), 6 deletions(-) diff --git a/docs/Generators/BOOM.rst b/docs/Generators/BOOM.rst index e04bed8f..caa7807e 100644 --- a/docs/Generators/BOOM.rst +++ b/docs/Generators/BOOM.rst @@ -8,4 +8,4 @@ Like the R10k and the 21264, BOOM is a unified physical register file design (al 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 __`. +Additional information about the BOOM micro-architecture can be found in the `BOOM documentation pages `__. diff --git a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst b/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst index 6b4c58c5..17d8c51a 100644 --- a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst +++ b/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst @@ -14,7 +14,8 @@ In contrast, the processor communicates with a RoCC accelerators through a custo Each core can have up to four accelerators that are controlled by custom instructions and share resources with the CPU. RoCC coprocessor instructions have the following form. -.. code-block:: +.. code-block:: none + customX rd, rs1, rs2, funct The X will be a number 0-3, and determines the opcode of the instruction, which controls which accelerator an instruction will be routed to. @@ -29,7 +30,8 @@ Integrating into the Generator Build System While developing, you want to include Chisel code in a submodule so that it can be shared by different projects. To add a submodule to the REBAR framework, make sure that your project is organized as follows. -.. code-block:: +.. code-block:: none + yourproject/ build.sbt src/main/scala/ @@ -39,12 +41,14 @@ Put this in a git repository and make it accessible. Then add it as a submodule to under the following directory hierarchy: ``generators/yourproject``. .. code-block:: shell + cd generators/ git submodule add https://git-repository.com/yourproject.git Then add ``yourproject`` to the REBAR top-level build.sbt file. .. code-block:: scala + lazy val yourproject = project.settings(commonSettings).dependsOn(rocketchip) You can then import the classes defined in the submodule in a new project if @@ -52,6 +56,7 @@ you add it as a dependency. For instance, if you want to use this code in the ``example`` project, change the final line in build.sbt to the following. .. code-block:: scala + lazy val example = (project in file(".")).settings(commonSettings).dependsOn(testchipip, yourproject) Finally, add ``yourproject`` to the ``PACKAGES`` variable in the ``common.mk`` file in the REBAR top level. @@ -64,6 +69,7 @@ The easiest way to create a TileLink peripheral is to use the ``TLRegisterRouter To create a RegisterRouter-based peripheral, you will need to specify a parameter case class for the configuration settings, a bundle trait with the extra top-level ports, and a module implementation containing the actual RTL. .. code-block:: scala + case class PWMParams(address: BigInt, beatBytes: Int) trait PWMTLBundle extends Bundle { @@ -98,6 +104,7 @@ The second set of arguments is the IO bundle constructor, which we create by ext The final set of arguments is the module constructor, which we create by extends ``TLRegModule`` with our module trait. .. code-block:: scala + class PWMTL(c: PWMParams)(implicit p: Parameters) extends TLRegisterRouter( c.address, "pwm", Seq("ucbbar,pwm"), @@ -116,6 +123,7 @@ The ``LazyModule`` trait runs setup code that must execute before all the hardwa For a simple memory-mapped peripheral, this just involves connecting the peripheral's TileLink node to the MMIO crossbar. .. code-block:: scala + trait HasPeripheryPWM extends HasSystemNetworks { implicit val p: Parameters @@ -138,6 +146,7 @@ Since this module has an extra `pwmout` output, we declare that in this trait, u We then connect the ``PWMTL``'s pwmout to the pwmout we declared. .. code-block:: scala + trait HasPeripheryPWMModuleImp extends LazyMultiIOModuleImp { implicit val p: Parameters val outer: HasPeripheryPWM @@ -151,6 +160,7 @@ Now we want to mix our traits into the system as a whole. This code is from ``generators/example/src/main/scala/Top.scala``. .. code-block:: scala + class ExampleTopWithPWM(q: Parameters) extends ExampleTop(q) with PeripheryPWM { override lazy val module = Module( @@ -170,6 +180,7 @@ The ``ExampleTopModule`` class is the actual RTL that gets synthesized. Finally, we need to add a configuration class in ``generators/example/src/main/scala/Configs.scala`` that tells the ``TestHarness`` to instantiate ``ExampleTopWithPWM`` instead of the default ``ExampleTop``. .. code-block:: scala + class WithPWM extends Config((site, here, up) => { case BuildTop => (p: Parameters) => Module(LazyModule(new ExampleTopWithPWM()(p)).module) @@ -181,6 +192,7 @@ Finally, we need to add a configuration class in ``generators/example/src/main/s Now we can test that the PWM is working. The test program is in ``tests/pwm.c``. .. code-block:: c + #define PWM_PERIOD 0x2000 #define PWM_DUTY 0x2008 #define PWM_ENABLE 0x2010 @@ -214,6 +226,7 @@ Compiling this program with make produces a ``pwm.riscv`` executable. Now with all of that done, we can go ahead and run our simulation. .. code-block:: shell + cd verisim make CONFIG=PWMConfig ./simulator-example-PWMConfig ../tests/pwm.riscv @@ -225,6 +238,7 @@ RoCC accelerators are lazy modules that extend the ``LazyRoCC`` class. Their implementation should extends the ``LazyRoCCModule`` class. .. code-block:: scala + class CustomAccelerator(opcodes: OpcodeSet) (implicit p: Parameters) extends LazyRoCC(opcodes) { override lazy val module = new CustomAcceleratorModule(this) @@ -273,6 +287,7 @@ This takes a sequence of functions producing ``LazyRoCC`` objects, one for each For instance, if we wanted to add the previously defined accelerator and route custom0 and custom1 instructions to it, we could do the following. .. code-block:: scala + class WithCustomAccelerator extends Config((site, here, up) => { case BuildRoCC => Seq((p: Parameters) => LazyModule( new CustomAccelerator(OpcodeSet.custom0 | OpcodeSet.custom1)(p))) @@ -288,6 +303,7 @@ IO devices or accelerators (like a disk or network driver), we may want to have To add a device like that, you would do the following. .. code-block:: scala + class DMADevice(implicit p: Parameters) extends LazyModule { val node = TLClientNode(TLClientParameters( name = "dma-device", sourceId = IdRange(0, 1))) diff --git a/docs/Simulation/Commercial-Simulators.rst b/docs/Simulation/Commercial-Simulators.rst index 1d2f8d35..36c3ef3b 100644 --- a/docs/Simulation/Commercial-Simulators.rst +++ b/docs/Simulation/Commercial-Simulators.rst @@ -22,11 +22,13 @@ You can then use this executable to run any compatible RV64 code. For instance, to run one of the riscv-tools assembly tests. .. code-block:: shell + ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple If you later create your own project, you can use environment variables to build an alternate configuration. .. code-block:: shell + make SUB_PROJECT=yourproject ./simulator-- ... diff --git a/docs/Simulation/Open-Source-Simulators.rst b/docs/Simulation/Open-Source-Simulators.rst index 53ca3a43..11d8d696 100644 --- a/docs/Simulation/Open-Source-Simulators.rst +++ b/docs/Simulation/Open-Source-Simulators.rst @@ -18,11 +18,13 @@ You can then use this executable to run any compatible RV64 code. For instance, to run one of the riscv-tools assembly tests. .. code-block:: shell + ./simulator-example-DefaultRocketConfig $RISCV/riscv64-unknown-elf/share/riscv-tests/isa/rv64ui-p-simple If you later create your own project, you can use environment variables to build an alternate configuration. .. code-block:: shell + make SUB_PROJECT=yourproject ./simulator-- ... diff --git a/docs/Tools/Chisel.rst b/docs/Tools/Chisel.rst index 3c8293a5..947f9666 100644 --- a/docs/Tools/Chisel.rst +++ b/docs/Tools/Chisel.rst @@ -16,4 +16,4 @@ However, if that passes, the output of the generator gives you an FIRRTL file an See :ref:`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 `__. -Otherwise, for all things Chisel related including API documentation, news, etc, visit their `website <>`__. +Otherwise, for all things Chisel related including API documentation, news, etc, visit their `website `__. diff --git a/docs/conf.py b/docs/conf.py index 6afa68ba..9b7bbe43 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,7 +36,8 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', - 'sphinx.ext.githubpages'] + 'sphinx.ext.githubpages', + 'sphinx.ext.autosectionlabel'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/index.rst b/docs/index.rst index 73b92ad4..68598e7a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,7 +8,7 @@ Welcome to REBAR's documentation! REBAR is a 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 intergration between open-source and commercial tools for the development of systems-on-chip. -New to REBAR? Jump to the :ref:`Getting Starting` page for more info. +New to REBAR? Jump to the :ref:`Getting Started` page for more info. .. toctree:: :maxdepth: 3