diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..e35d8850c9 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/conf.py b/docs/conf.py index 5e06b0a370..d12844bc1b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -66,7 +66,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = None +pygments_style = 'sphinx' # -- Options for HTML output ------------------------------------------------- diff --git a/docs/sections/IntroductionOverview/BOOM-Repository.rst b/docs/sections/IntroductionOverview/BOOM-Repository.rst index 3cf51cee7f..15e613c457 100644 --- a/docs/sections/IntroductionOverview/BOOM-Repository.rst +++ b/docs/sections/IntroductionOverview/BOOM-Repository.rst @@ -5,68 +5,92 @@ The BOOM repository holds the source code to the BOOM core; it is not a full processor and thus is **NOT A SELF-RUNNING** repository. To instantiate a BOOM core, the Rocket chip generator found in the rocket-chip git repository must be used -(), which provides the caches, +https://github.com/ucb-bar/rocket-chip, which provides the caches, uncore, and other needed infrastructure to support a full processor. -The BOOM source code can be found in `boom/src/main/scala`. +The BOOM source code can be found in boom/src/main/scala. The code structure is shown below: -- `boom/src/main/scala`/ - - - bpd\_pipeline.scala [ branch prediction stage.]{} - - - brpredictor.scala [ abstract branch predictor.]{} - - - configs.scala [ BOOM configurations. ]{} - - - consts.scala [ constant definitions. ]{} - - - core.scala [ the top-level of the processor core.]{} - - - dcacheshim.scala [ the shim between the the core and the - dcache.]{} - - - decode.scala [ decode stage.]{} - - - execute.scala [ high-level execution units (made up of - FUs).]{} - - - fpu.scala [ floating point unit.]{} - - - functional\_unit.scala [ low-level functional units.]{} - - - gshare.scala [ gshare branch predictor.]{} - - - imul.scala [ integer multiplier.]{} - - - issue\_ageordered.scala [ age-ordered (collasping-queue) issue - window implementation.]{} - - - issue.scala [ abstract issue window.]{} - - - issue\_slot.scala [ An issue window slot.]{} - - - issue\_unordered.scala [ un-ordered issue window - implementation.]{} - - - lsu.scala [ load/store unit.]{} - - - package.scala [ ]{} - - - parameters.scala [ knobs/parameters.]{} - - - prefetcher.scala [ data prefetcher.]{} - - - regfile.scala [ register file.]{} - - - registerread.scala [ registerRead stage and bypassing.]{} - - - rename.scala [ register renaming logic.]{} - - - rob.scala [ re-order buffer.]{} - - - tile.scala [ top-level tile.]{} - - - util.scala [ utility code.]{} - +* boom/src/main/scala/ + + * bpu/ + + * 2bc-table.scala + * base-only.scala + * bim.scala + * bpd-pipeline.scala + * brpredictor.scala + * btb-sa.scala + * btb.scala + * dense-btb.scala + * gshare.scala + * tage.scala + * tage-table.scala + + * common/ + + * configs + * consts + * microop + * package + * parameters + * tile + * types + + * exu/ + + * core.scala + * decode.scala + * execute.scala + * execution_units.scala + * fdiv.scala + * fppipeline.scala + * fpu.scala + * fudecode.scala + * functional_unit.scala + * imul.scala + * issue_ageordered.scala + * issue.scala + * issue_slot.scala + * issue_unordered.scala + * regfile-custom.scala + * regfile.scala + * registerread.scala + * rename-busytable.scala + * rename-freelist.scala + * rename-maptable.scala + * rename.scala + * rob.scala + + * ifu/ + + * branchchecker.scala + * fetchbuffer.scala + * fetchmonitor.scala + * fetch.scala + * fetchtargetqueue.scala + * frontend.scala + * icache.scala + + * lsu/ + + * dcacheshim.scala + * lsu.scala + * types.scala + + * system/ + + * BoomSubsystem.scala + * BoomTestSuites.scala + * Configs.scala + * ExampleBoomSystem.scala + * Generator.scala + * TestHarness.scala + + * util/ + + * elastic-reg.scala + * elastic-sram.scala + * seqmem-transformable.scala + * util.scala diff --git a/docs/sections/IntroductionOverview/Chisel-HCL.rst b/docs/sections/IntroductionOverview/Chisel-HCL.rst index 144196eeca..234819d020 100644 --- a/docs/sections/IntroductionOverview/Chisel-HCL.rst +++ b/docs/sections/IntroductionOverview/Chisel-HCL.rst @@ -1,7 +1,7 @@ The  Hardware Construction Language ==================================== -BOOM is implemented in the  hardware construction language. More -information about  can be found at (). +BOOM is implemented in the hardware construction language. More +information about can be found at http://chisel.eecs.berkeley.edu. diff --git a/docs/sections/IntroductionOverview/Quick-start.rst b/docs/sections/IntroductionOverview/Quick-start.rst index cb377bf910..6f7e7672be 100644 --- a/docs/sections/IntroductionOverview/Quick-start.rst +++ b/docs/sections/IntroductionOverview/Quick-start.rst @@ -1,21 +1,25 @@ Quick-start ==================================== -To build a BOOM C++ emulator and run BOOM through a couple of simple -tests: +The best way to get started with the BOOM core is to use the BOOM project template located in the +main `GitHub organization `__. There you will find the main steps +to setup your environment, build, and run the BOOM core on a C++ emulator. Here is a selected set of steps +from that repositories README: -``` +:: -git clone https://github.com/ucb-bar/rocket-chip.git -cd rocket-chip -git checkout boom -git submodule update --init -cd emulator -make run CONFIG=BOOMConfig + git clone https://github.com/riscv-boom/boom-template.git + cd boom-template + ./scripts/init-submodules.sh + + # You may want to add the following two lines to your shell profile + export RISCV=/path/to/install/dir + export PATH=$RISCV/bin:$PATH -``` - -Note: This assumes you have already installed the riscv-tools toolchain. If -not, visit (). + cd boom-template + ./scripts/build-tools.sh + cd verisim + make run +Note: This assumes you have don't have installed the riscv-tools toolchain. It will pull and build the toolchain for you. diff --git a/docs/sections/IntroductionOverview/RISCV-ISA.rst b/docs/sections/IntroductionOverview/RISCV-ISA.rst index 1b922436d8..0735f6660c 100644 --- a/docs/sections/IntroductionOverview/RISCV-ISA.rst +++ b/docs/sections/IntroductionOverview/RISCV-ISA.rst @@ -5,32 +5,32 @@ BOOM implements the RV64G variant of the RISC-V ISA. This includes the MAFD extensions and the privileged specification (multiply/divide, AMOs, load-reserve/store-conditional, single- and double-precision IEEE 754-2008 floating point). More information about the RISC-V ISA can be -found at (). +found at http://riscv.org. RISC-V provides the following features which make it easy to target with high-performance designs: -> This greatly simplifies the Load/Store Unit, which does not need to -> have loads snoop other loads nor does coherence traffic need to snoop -> the LSU, as required by sequential consistency. -> -> The fp status register does not need to be renamed, nor can FP -> instructions throw exceptions themselves. -> -> All integer ALU operations exhibit no side-effects, save the writing -> of the destination register. This prevents the need to rename -> additional condition state. -> -> Although predication can lower the branch predictor complexity of -> small designs, it greatly complicates OoO pipelines, including the -> addition of a third read port for integer operations. -> -> Even JAL requires specifying an explicit . This simplifies rename -> logic, which prevents either the need to know the instruction first -> before accessing the rename tables, or it prevents adding more ports -> to remove the instruction decode off the critical path. -> -> This allows decode and rename to proceed in parallel. + This greatly simplifies the Load/Store Unit, which does not need to + have loads snoop other loads nor does coherence traffic need to snoop + the LSU, as required by sequential consistency. + + The fp status register does not need to be renamed, nor can FP + instructions throw exceptions themselves. + + All integer ALU operations exhibit no side-effects, save the writing + of the destination register. This prevents the need to rename + additional condition state. + + Although predication can lower the branch predictor complexity of + small designs, it greatly complicates OoO pipelines, including the + addition of a third read port for integer operations. + + Even JAL requires specifying an explicit . This simplifies rename + logic, which prevents either the need to know the instruction first + before accessing the rename tables, or it prevents adding more ports + to remove the instruction decode off the critical path. + + This allows decode and rename to proceed in parallel. BOOM (currently) does not implement the “C" compressed extension nor the “V" vector extension. diff --git a/docs/sections/IntroductionOverview/Rocket-Chip.rst b/docs/sections/IntroductionOverview/Rocket-Chip.rst index 85892fcbf0..98c6055631 100644 --- a/docs/sections/IntroductionOverview/Rocket-Chip.rst +++ b/docs/sections/IntroductionOverview/Rocket-Chip.rst @@ -3,7 +3,7 @@ The Rocket-chip Repository Layout As BOOM is just a core, an entire SoC infrastructure must be provided. BOOM was developed to use the open-source Rocket-chip SoC generator -(). The Rocket-chip generator +https://github.com/ucb-bar/rocket-chip. The Rocket-chip generator can instantiate a wide range of SoC designs, including cache-coherent multi-tile designs, cores with and without accelerators, and chips with or without a last-level shared cache. @@ -13,58 +13,36 @@ Rocket-chip, the Rocket-chip repository makes heavy use of git submodules. The directory structure of the Rocket-chip repository is shown below. -> - `rocket-chip`/ -> -> - boom/ [ Git submodule of the  source code for the BOOM -> core.]{} -> -> - chisel [ The source code to the [Chisel]{} language itself.]{} -> -> - firrtl [ The source code to the [FIRRTL]{} project.]{} -> -> - csrc/ [ Utility C/C++ source code.]{} -> -> - emulator/ [ Verilator simulation tools and support.]{} -> -> - generated-src/[ Auto-generated Verilog code.]{} -> -> - Makefile [ Makefile for Verilator simulation.]{} -> -> - output/[ Output files from Verilator simulation runs.]{} -> -> - riscv-tools/[ Git submodule that points to the RISC-V -> toolchain.]{} -> -> - riscv-tests/ [ Source code for benchmarks and tests.]{} -> -> - riscv-bmarks/ [ Benchmarks written in C.]{} -> -> - riscv-tests/ [ Tests written in assembly.]{} -> -> - Makefrag [ The high-level Makefile fragment.]{} -> -> - src/ [  source code for rocket-chip.]{} -> -> - rocket/ [ Git submodule of the  source code for the Rocket -> core (used as a library of processor components).]{} -> -> - junctions/ [ Git submodule of the  source code for the -> uncore and off-chip network.]{} -> -> - uncore/ [ Git submodule of the  source code for the uncore -> components (including LLC).]{} -> -> - sbt/ [/Scala voodoo.]{} -> -> - vsim/ [ The ASIC Verilog simulation and build directories. ]{} -> -### The Rocket Core - a Library of Processor Components! {#sec:rocket} +* rocket-chip/ + + * boom/ **Git submodule of the  source code for the BOOM core.** + * chisel **The source code to the Chisel language itself.** + * firrtl **The source code to the FIRRTL project.** + * csrc/ **Utility C/C++ source code.** + * emulator/ **Verilator simulation tools and support.** + * generated-src/ **Auto-generated Verilog code.** + * Makefile **Makefile for Verilator simulation.** + * output/ **Output files from Verilator simulation runs.** + * riscv-tools/ **Git submodule that points to the RISC-V toolchain.** + * riscv-tests/ **Source code for benchmarks and tests.** + * riscv-bmarks/ **Benchmarks written in C.** + * riscv-tests/ **Tests written in assembly.** + * Makefrag **The high-level Makefile fragment.** + * src/ **source code for rocket-chip.** + * rocket/ **Git submodule of the  source code for the Rocket core (used as a library of processor components).** + * junctions/ **Git submodule of the  source code for the uncore and off-chip network.** + * uncore/ **Git submodule of the  source code for the uncore components (including LLC).** + * sbt/ **Scala voodoo.** + * vsim/ **The ASIC Verilog simulation and build directories.** + +The Rocket Core - a Library of Processor Components! +------------------------------------------------------------------- Rocket is a 5-stage in-order core that implements the RV64G ISA and page-based virtual memory. The original design purpose of the Rocket core was to enable architectural research into vector co-processors by -serving as the scalar [*Control Processor*]{}. Some of that work can be -found at ().[@hwacha] +serving as the scalar **Control Processor**. Some of that work can be +found at http://hwacha.org. Rocket has been taped out at least thirteen times in three different commercial processes, and has been successfully demonstrated to reach @@ -80,7 +58,6 @@ caches, the translation look-aside buffers, the page table walker, and more. Thus, throughout this document you will find references to these Rocket components and descriptions on how they fit into BOOM. -The source code to Rocket can be found at -().[@rocket] +The source code to Rocket can be found at https://github.com/freechipsproject/rocket-chip. diff --git a/docs/sections/IntroductionOverview/index.rst b/docs/sections/IntroductionOverview/index.rst index 5dd4b844df..2a76b7337b 100644 --- a/docs/sections/IntroductionOverview/index.rst +++ b/docs/sections/IntroductionOverview/index.rst @@ -5,11 +5,11 @@ The goal of this document is to describe the design and implementation of the Berkeley Out–of–Order Machine (BOOM). BOOM is heavily inspired by the MIPS R10k and the Alpha 21264 -out–of–order processors[@alpha21264; @mipsr10k]. Like the R10k and the +out–of–order processors. Like the R10k and the 21264, BOOM is a unified physical register file design (also known as “explicit register renaming"). -The source code to BOOM can be found at (). +The source code to BOOM can be found at https://github.com/riscv-boom/riscv-boom. .. toctree:: :maxdepth: 2