diff --git a/docs/Advanced-Concepts/Chip-Communication.rst b/docs/Advanced-Concepts/Chip-Communication.rst index 902a32a3..92efd17c 100644 --- a/docs/Advanced-Concepts/Chip-Communication.rst +++ b/docs/Advanced-Concepts/Chip-Communication.rst @@ -74,7 +74,7 @@ In order to communicate with the DUT with the DMI protocol, the DUT needs to con The DTM is given in the `RISC-V Debug Specification `__ and is responsible for managing communication between the DUT and whatever lives on the other side of the DMI (in this case FESVR). This is implemented in the Rocket Chip ``Subsystem`` by having the ``HasPeripheryDebug`` and ``HasPeripheryDebugModuleImp`` mixins. - During simulation, the host sends DMI commands to a +During simulation, the host sends DMI commands to a simulation stub called ``SimDTM`` (C++ class) that resides in a ``SimDTM`` verilog module (both are located in the ``generators/rocket-chip`` project). This ``SimDTM`` verilog module then sends the DMI command recieved by the simulation stub into the DUT which then converts the DMI diff --git a/docs/Advanced-Concepts/Top-Testharness.rst b/docs/Advanced-Concepts/Top-Testharness.rst index a0f7f775..1256ea59 100644 --- a/docs/Advanced-Concepts/Top-Testharness.rst +++ b/docs/Advanced-Concepts/Top-Testharness.rst @@ -1,5 +1,5 @@ Tops, Test-Harnesses, and the Test-Driver -==================================== +=========================================== The three highest levels of hierarchy in a Chipyard SoC are the Top (DUT), ``TestHarness``, and the ``TestDriver``. diff --git a/docs/Chipyard-Basics/Chipyard-Components.rst b/docs/Chipyard-Basics/Chipyard-Components.rst index 6d54ad94..ac86bac4 100644 --- a/docs/Chipyard-Basics/Chipyard-Components.rst +++ b/docs/Chipyard-Basics/Chipyard-Components.rst @@ -29,6 +29,13 @@ Accelerators Hwacha integrates with a Rocket or BOOM core using the RoCC (Rocket Custom Co-processor) interface. See :ref:`Hwacha` for more information. +.. Fixed Function Accelerators: + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + TBD +**SHA3** + A fixed-function accelerator for the SHA3 hash function. This simple accelerator is used as a demonstration for some of the + Chipyard integration flows using the RoCC interface. + System Components: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -45,9 +52,6 @@ System Components: **testchipip** A collection of utilities used for testing chips and interfacing them with larger test environments. -.. Fixed Function Accelerators: - ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - TBD Tools ------------------------------------------- @@ -68,6 +72,9 @@ Tools A collection of common FIRRTL transformations used to manipulate a digital circuit without changing the generator source RTL. See :ref:`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). + Toolchains ------------------------------------------- @@ -105,9 +112,9 @@ Sims 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. +**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. + 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. diff --git a/docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst b/docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst deleted file mode 100644 index 7599edc3..00000000 --- a/docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst +++ /dev/null @@ -1,133 +0,0 @@ -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 - - - - - - - - - - diff --git a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst index e83bc9e2..2cb36656 100644 --- a/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst +++ b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst @@ -129,7 +129,8 @@ contain the implementation for the module, and may instantiate other normal modules OR lazy modules (for nested Diplomacy graphs, for example). - Mix-in + +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. diff --git a/docs/Chipyard-Basics/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst index 499939f4..28555bbc 100644 --- a/docs/Chipyard-Basics/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -24,12 +24,12 @@ 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. +For custom installations, Each tool within the toolchains contains individual installation procedures within its README file. +To get a basic installation (which is the only thing needed for most Chipyard use-cases), just the following steps are necessary. .. code-block:: shell - ./scripts/build-toolchains.sh riscv # for a normal risc-v toolchain + ./scripts/build-toolchains.sh riscv-tools # for a normal risc-v toolchain # OR diff --git a/docs/Simulation/FPGA-Accelerated-Simulators.rst b/docs/Simulation/FPGA-Accelerated-Simulation.rst similarity index 97% rename from docs/Simulation/FPGA-Accelerated-Simulators.rst rename to docs/Simulation/FPGA-Accelerated-Simulation.rst index 29f42880..e4142d6c 100644 --- a/docs/Simulation/FPGA-Accelerated-Simulators.rst +++ b/docs/Simulation/FPGA-Accelerated-Simulation.rst @@ -1,6 +1,6 @@ .. _firesim-sim-intro: -FPGA-Accelerated Simulators +FPGA-Accelerated Simulation ============================== FireSim @@ -17,7 +17,7 @@ documentation `__. Then clone Chipyard onto your FireSim manager instance, and setup your Chipyard repository as you would normally. -Next, initalize FireSim as library in Chipyard by running: +Next, initalize FireSim as a library in Chipyard by running: .. code-block:: shell diff --git a/docs/Simulation/Running-A-Simulation.rst b/docs/Simulation/Running-A-Simulation.rst deleted file mode 100644 index a4346ed5..00000000 --- a/docs/Simulation/Running-A-Simulation.rst +++ /dev/null @@ -1,108 +0,0 @@ -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 (Open-Source)` or :ref:`Synopsys VCS (License Required)`. -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 - -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 ``<...>--``. -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 - ./<...>-- 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/<...>--/`` 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 - diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst index 8341c7ae..c15283d3 100644 --- a/docs/Simulation/index.rst +++ b/docs/Simulation/index.rst @@ -19,5 +19,5 @@ Click next to see how to run a simulation. :caption: Simulation: Software-RTL-Simulation - FPGA-Accelerated-Simulators + FPGA-Accelerated-Simulation diff --git a/docs/VLSI/Hammer.rst b/docs/VLSI/Hammer.rst index 11d80a07..ddfc071b 100644 --- a/docs/VLSI/Hammer.rst +++ b/docs/VLSI/Hammer.rst @@ -3,7 +3,7 @@ Core Hammer ================================ -`Hammer `__ is a physical design generator that wraps around vendor specific technologies and tools to provide a single API to create ASICs. +`Hammer `__ is a physical design flow which encourages reusability by partitioning physical design specifications into three distinct concerns: design, CAD tool, and process technology. Hammer wraps around vendor specific technologies and tools to provide a single API to address ASIC design concerns. Hammer allows for reusability in ASIC design while still providing the designers leeway to make their own modifications. For more information, read the `Hammer paper `__ and see the `GitHub repository `__ and associated documentation.