Welcome to RISCV-BOOM's documentation!
======================================

The Berkeley Out-of-Order Machine (BOOM) is a synthesizable and parameterizable open-source `RISC-V <riscv.org>`__ out-of-order core written in the `Chisel <chisel-lang.org>`__ hardware construction language.
The goal of this document is to describe the design and implementation of the core as well as provide other helpful information to use the core.

Useful Links
------------

The BOOM source code can be found here: https://github.com/riscv-boom/riscv-boom.

The main supported mechanism to use the core is to use the Chipyard framework: https://github.com/ucb-bar/chipyard.

The BOOM website can be found here: https://boom-core.org.

The BOOM mailing list can be found here: https://groups.google.com/forum/#!forum/riscv-boom.

Quick-start
-----------

The best way to get started with the BOOM core is to use the `Chipyard project template <https://github.com/ucb-bar/chipyard>`__.
There you will find the main steps to setup your environment, build, and run the BOOM core on a C++ emulator.
Chipyard also provides supported flows for pushing a BOOM-based SoC through both the FireSim FPGA simulation flow and the HAMMER ASIC flow.
Here is a selected set of steps from `Chipyard's documentation <https://chipyard.readthedocs.io/en/latest/>`__:

.. _quick-start-code:
.. code-block:: bash
    :caption: Quick-Start Code

    # Download the template and setup environment
    git clone https://github.com/ucb-bar/chipyard.git
    cd chipyard
    ./scripts/init-submodules-no-riscv-tools.sh

    # build the toolchain
    ./scripts/build-toolchains.sh riscv-tools

    # add RISCV to env, update PATH and LD_LIBRARY_PATH env vars
    # note: env.sh generated by build-toolchains.sh
    source env.sh

    cd sims/verilator
    make CONFIG=LargeBoomConfig

.. Note:: :numref:`quick-start-code` assumes you don't have riscv-tools toolchain installed. It will pull and build the toolchain for you.

Table of Contents
-----------------

.. toctree::
   :maxdepth: 2
   :caption: Introduction:

   sections/intro-overview/boom
   sections/intro-overview/boom-pipeline
   sections/intro-overview/chisel
   sections/intro-overview/riscv-isa
   sections/intro-overview/rocket-chip

.. toctree::
   :maxdepth: 2
   :caption: Core Overview:

   sections/instruction-fetch-stage
   sections/branch-prediction/index
   sections/decode-stage
   sections/rename-stage
   sections/reorder-buffer
   sections/issue-units
   sections/reg-file-bypass-network
   sections/execution-stages
   sections/load-store-unit
   sections/memory-system

.. toctree::
   :maxdepth: 2
   :caption: Usage:

   sections/parameterization
   sections/boom-ecosystem
   sections/debugging
   sections/uarch-counters
   sections/verification
   sections/physical-realization

.. toctree::
   :maxdepth: 2
   :caption: Other:

   sections/future-work
   sections/faq
   sections/terminology

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
