diff --git a/docs/ReBAR-Basics/Adding-An-Accelerator-Tutorial.rst b/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst similarity index 100% rename from docs/ReBAR-Basics/Adding-An-Accelerator-Tutorial.rst rename to docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst diff --git a/docs/Getting-Started/Configs-Parameters-Mixins.rst b/docs/Getting-Started/Configs-Parameters-Mixins.rst new file mode 100644 index 00000000..8333816f --- /dev/null +++ b/docs/Getting-Started/Configs-Parameters-Mixins.rst @@ -0,0 +1,79 @@ +Configs, Parameters, Mix-ins, and Everything In Between +======================================================== + +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: + +**Parameter** + +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. + + +**Config** +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`, while the naming convention for a non-additive config will be ``. +Configs can take arguments which will in-turn set parameters in the specific configs. + +Example config: + +.. + class WithMyAcceleratorParams extends Config((site, here, up) => { + case MyAcceleratorKey => + MyAcceleratorConfig( + Rows = 2, + rowBits = 64, + Columns = 16, + hartId = 1, + some_length = 256, + ) + }) + +Example config which uses a higher level config: + +.. + class WithMyMoreComplexAcceleratorConfig extends Config((site, here, up) => { + case MyAcceleratorKey => + MyAcceleratorConfig( + Rows = 2, + rowBits = site(SystemBusKey).beatBits, + hartId = up(RocketTilesKey, site).length, + ) + }) + +Example of additive configs: + +.. + class SomeAdditiveConfig extends Config( + new WithMyMoreComplexAcceleratorConfig ++ + new WithMyAcceleratorParams ++ + new DefaultExampleConfig + ) + + +**Cake Pattern** +The cake pattern is a scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes refered to as dependancy injection). It is used in the Rocket chip SoC library and ReBAR framework in merging multiple system components and IO interfaces into a large system component. + +Example of using the cake pattern to merge multiple system components into a single top-level design, extending a basic Rocket SoC: + +.. + 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 convetion for an additive mix-in is `Has`. + diff --git a/docs/Getting-Started/ReBAR-Basics.rst b/docs/Getting-Started/ReBAR-Basics.rst new file mode 100644 index 00000000..eb54033e --- /dev/null +++ b/docs/Getting-Started/ReBAR-Basics.rst @@ -0,0 +1,86 @@ + + +ReBAR Basics +=============================== + + +Generators +------------------------------------------- +Generators are parametrized programs written as RTL code, designed to generate verilog 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. +The ReBAR Framework currently consists of the following generators: + +Processor Cores +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**Rocket** + An in-order RISC-V core. + +**BOOM (Berkeley Out-of-Order Machine)** + An out-of-order RISC-V core. + +Data-Parallel 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 + + +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 utilites 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 emdedding hardware generation primitives in the Scala programming language. The Chisel compilter elaborate the generator into a FIRRTL output. + +**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. + +**BARSTOOLS** + A collection of common FIRRTL transformations used to manipulate a digital circuit without changing the generator source RTL. + + +Toolchains +------------------------------------------- +**riscv-tools** + A collection of software toolchains used to develope 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 ReBAR 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 +------------------------------------------- +**verisim (Verilator wrapper)** + Verilator is an open source Verilog simulator. The verisim 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). + +**vsim (VCS wrapper)** + VCS is a proprietary Verilog simulator. Assuming the user has valid VCS licenses and installations, the vsim 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). + +**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 clound 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. + + +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 desing contraints. 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 contraints relating to that process technology (obsolete standard cells, metal layer routing contraints, etc.). The HAMMER flow requires access to proprietry EDA tools and process technology libraries. diff --git a/docs/Getting-Started/Running-A-Simulation.rst b/docs/Getting-Started/Running-A-Simulation.rst new file mode 100644 index 00000000..3be148fa --- /dev/null +++ b/docs/Getting-Started/Running-A-Simulation.rst @@ -0,0 +1,100 @@ +Running A Simulation +======================================================== + +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. + + +Software RTL Simulation +------------------------ +The ReBAR framework provides wrappers for two common software RTL simulators: the open-source Verilator simulator. and the proprietry VCS simulator.The following instructions assume at least one of these simulators is installed. + +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: + +.. + make TOP= CONFIG= SBT_PROJECT= MODEL= + +Where `` is the class name of the top level design, ` CONFIG= SBT_PROJECT= MODEL= + +or + +.. + make run-asm-tests SUB_PROJECT=example + + + +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: + +.. + make TOP= CONFIG= SBT_PROJECT= MODEL= + +Where `` is the class name of the top level design, ` CONFIG= SBT_PROJECT= MODEL= + +or + +.. + make run-asm-tests SUB_PROJECT=example + + + +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. There FireSim simulation require 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 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. + +TODO: Continue from here + diff --git a/docs/ReBAR-Basics/index.rst b/docs/Getting-Started/index.rst similarity index 78% rename from docs/ReBAR-Basics/index.rst rename to docs/Getting-Started/index.rst index af625cca..50a753cc 100644 --- a/docs/ReBAR-Basics/index.rst +++ b/docs/Getting-Started/index.rst @@ -13,7 +13,10 @@ Hit next to get started! .. toctree:: :maxdepth: 2 - :caption: ReBAR Basics: + :caption: Getting Started: - rebar-generator-mixins + ReBAR-Basics + Configs-Parameters-Mixins Adding-An-Accelerator-Tutorial + Running-A-Simulation + rebar-generator-mixins diff --git a/docs/ReBAR-Basics/rebar-generator-mixins.rst b/docs/Getting-Started/rebar-generator-mixins.rst similarity index 100% rename from docs/ReBAR-Basics/rebar-generator-mixins.rst rename to docs/Getting-Started/rebar-generator-mixins.rst diff --git a/docs/index.rst b/docs/index.rst index 74d754d6..4123f632 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,7 +45,7 @@ The documentation outline should look like this :caption: Getting Started: :numbered: - ReBAR-Basics/index + Getting-Started/index Indices and tables