Updated Intro/Overview

docs/.gitignore

@@ -0,0 +1 @@
+_build

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 -------------------------------------------------

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
-(<https://github.com/ucb-bar/rocket-chip>), 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

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 (<http://chisel.eecs.berkeley.edu>).
+BOOM is implemented in the hardware construction language. More
+information about can be found at http://chisel.eecs.berkeley.edu.
 
 

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 <https://github.com/riscv-boom/boom-template>`__. 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 (<https://github.com/riscv/riscv-tools>).
+    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.

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 (<http://riscv.org>).
+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.

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
-(<https://github.com/ucb-bar/rocket-chip>). 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 (<http://hwacha.org>).[@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
-(<https://github.com/ucb-bar/rocket>).[@rocket]
+The source code to Rocket can be found at https://github.com/freechipsproject/rocket-chip.
 
 

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 (<https://ucb-bar.github.io/riscv-boom>).
+The source code to BOOM can be found at https://github.com/riscv-boom/riscv-boom.
 
 .. toctree::
     :maxdepth: 2