diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst index 62dd11aa..ef8988be 100644 --- a/docs/Advanced-Usage/index.rst +++ b/docs/Advanced-Usage/index.rst @@ -4,8 +4,3 @@ Advanced Usage The following sections are advanced topics about how to use Chipyard and special features of the framework. They expect you to know about Chisel, Parameters, Configs, etc. -.. toctree:: - :maxdepth: 2 - :caption: Getting Started: - - Heterogeneous-SoCs diff --git a/docs/Chipyard-Basics/Building-A-Chip.rst b/docs/Chipyard-Basics/Building-A-Chip.rst new file mode 100644 index 00000000..17fb4512 --- /dev/null +++ b/docs/Chipyard-Basics/Building-A-Chip.rst @@ -0,0 +1,3 @@ +Building A Chip +============================== +TODO diff --git a/docs/Getting-Started/Chipyard-Basics.rst b/docs/Chipyard-Basics/Chipyard-Components.rst similarity index 99% rename from docs/Getting-Started/Chipyard-Basics.rst rename to docs/Chipyard-Basics/Chipyard-Components.rst index c5aa5a62..8285644f 100644 --- a/docs/Getting-Started/Chipyard-Basics.rst +++ b/docs/Chipyard-Basics/Chipyard-Components.rst @@ -1,4 +1,4 @@ -Chipyard Basics +Chipyard Components =============================== Generators diff --git a/docs/Getting-Started/Chipyard-Generator-Mixins.rst b/docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst similarity index 100% rename from docs/Getting-Started/Chipyard-Generator-Mixins.rst rename to docs/Chipyard-Basics/Chipyard-Generator-Mixins.rst diff --git a/docs/Getting-Started/Configs-Parameters-Mixins.rst b/docs/Chipyard-Basics/Configs-Parameters-Mixins.rst similarity index 100% rename from docs/Getting-Started/Configs-Parameters-Mixins.rst rename to docs/Chipyard-Basics/Configs-Parameters-Mixins.rst diff --git a/docs/Getting-Started/Development-Ecosystem.rst b/docs/Chipyard-Basics/Development-Ecosystem.rst similarity index 100% rename from docs/Getting-Started/Development-Ecosystem.rst rename to docs/Chipyard-Basics/Development-Ecosystem.rst diff --git a/docs/Getting-Started/Initial-Repo-Setup.rst b/docs/Chipyard-Basics/Initial-Repo-Setup.rst similarity index 88% rename from docs/Getting-Started/Initial-Repo-Setup.rst rename to docs/Chipyard-Basics/Initial-Repo-Setup.rst index 58a40d56..7b7042ee 100644 --- a/docs/Getting-Started/Initial-Repo-Setup.rst +++ b/docs/Chipyard-Basics/Initial-Repo-Setup.rst @@ -8,8 +8,8 @@ After cloning this repo, you will need to initialize all of the submodules. .. code-block:: shell - git clone https://github.com/ucb-bar/project-template.git - cd project-template + git clone https://github.com/ucb-bar/chipyard.git + cd chipyard ./scripts/init-submodules-no-riscv-tools.sh Building a Toolchain @@ -26,7 +26,7 @@ But to get a basic installation, just the following steps are necessary. # OR - ./scripts/build-toolchains.sh hwacha # for a hwacha modified risc-v toolchain + ./scripts/build-toolchains.sh esp-tools # for a modified risc-v toolchain with Hwacha vector instructions Once the script is run, a ``env.sh`` file is emitted at sets the ``PATH``, ``RISCV``, and ``LD_LIBRARY_PATH`` environment variables. You can put this in your ``.bashrc`` or equivalent environment setup file to get the proper variables. diff --git a/docs/Getting-Started/Running-A-Simulation.rst b/docs/Chipyard-Basics/Running-A-Simulation.rst similarity index 100% rename from docs/Getting-Started/Running-A-Simulation.rst rename to docs/Chipyard-Basics/Running-A-Simulation.rst diff --git a/docs/Chipyard-Basics/index.rst b/docs/Chipyard-Basics/index.rst new file mode 100644 index 00000000..be46c627 --- /dev/null +++ b/docs/Chipyard-Basics/index.rst @@ -0,0 +1,24 @@ +Chipyard Basics +================================ + +These guides will walk you through the basics of the Chipyard framework: + +- First, we will go over the components of the framework. + +- Next, we will go over the different configurations available. + +- Then, we will go over initial framework setup. + +- Finally, we will briefly walk through what you can do with the Chipyard tools. + +Hit next to get started! + +.. toctree:: + :maxdepth: 2 + :caption: Chipyard Basics: + + Chipyard-Components + Configs-Parameters-Mixins + Initial-Repo-Setup + Running-A-Simulation + Building-A-Chip diff --git a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst b/docs/Customization/Adding-An-Accelerator.rst similarity index 97% rename from docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst rename to docs/Customization/Adding-An-Accelerator.rst index 4edbde1b..611bf002 100644 --- a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst +++ b/docs/Customization/Adding-An-Accelerator.rst @@ -49,7 +49,7 @@ Then add ``yourproject`` to the Chipyard top-level build.sbt file. .. code-block:: scala - lazy val yourproject = project.settings(commonSettings).dependsOn(rocketchip) + lazy val yourproject = (project in file("generators/yourproject")).settings(commonSettings).dependsOn(rocketchip) You can then import the classes defined in the submodule in a new project if you add it as a dependency. For instance, if you want to use this code in @@ -62,6 +62,12 @@ the ``example`` project, change the final line in build.sbt to the following. Finally, add ``yourproject`` to the ``PACKAGES`` variable in the ``common.mk`` file in the Chipyard top level. This will allow make to detect that your source files have changed when building the Verilog/FIRRTL files. +.. code-block:: shell + + PACKAGES=$(addprefix generators/, rocket-chip testchipip boom hwacha sifive-blocks sifive-cache example yourproject) \ + $(addprefix sims/firesim/sim/, . firesim-lib midas midas/targetutils) + + MMIO Peripheral ------------------ diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Customization/Heterogeneous-SoCs.rst similarity index 100% rename from docs/Advanced-Usage/Heterogeneous-SoCs.rst rename to docs/Customization/Heterogeneous-SoCs.rst diff --git a/docs/Customization/Memory-Hierarchy.rst b/docs/Customization/Memory-Hierarchy.rst new file mode 100644 index 00000000..fc9792c4 --- /dev/null +++ b/docs/Customization/Memory-Hierarchy.rst @@ -0,0 +1,4 @@ +Memory Hierarchy +=============================== +TODO: Talk about SiFive Cache, and integration with L1 and backing main memory models +(maybe even Tilelink) diff --git a/docs/Customization/index.rst b/docs/Customization/index.rst new file mode 100644 index 00000000..c8cb9cc3 --- /dev/null +++ b/docs/Customization/index.rst @@ -0,0 +1,17 @@ +Customization +================================ + +These guides will walk you through customization of your system-on-chip: + +- Contructing heterogenous systems-on-chip using the Chipyard generators and configuration system. + +- Adding custom accelerators to your system-on-chip. + +Hit next to get started! + +.. toctree:: + :maxdepth: 2 + :caption: Customization: + Heterogeneous-SoCs + Adding-An-Accelerator + Memory-Hierarchy diff --git a/docs/Getting-Started/index.rst b/docs/Getting-Started/index.rst deleted file mode 100644 index dcfe0802..00000000 --- a/docs/Getting-Started/index.rst +++ /dev/null @@ -1,21 +0,0 @@ -Getting Started -================================ - -These guides will walk you through the basics of the Chipyard framework: - -- First, we will go over the different configurations available. - -- Then, we will walk through adding a custom accelerator. - -Hit next to get started! - -.. toctree:: - :maxdepth: 2 - :caption: Getting Started: - - Chipyard-Basics - Configs-Parameters-Mixins - Adding-An-Accelerator-Tutorial - Initial-Repo-Setup - Running-A-Simulation - Chipyard-Generator-Mixins diff --git a/docs/Quick-Start.rst b/docs/Quick-Start.rst new file mode 100644 index 00000000..e319a3d4 --- /dev/null +++ b/docs/Quick-Start.rst @@ -0,0 +1,43 @@ +Quick Start +=============================== + +Setting up the Chipyard Repo +------------------------------------------- + +Start by fetching Chipyard's sources. Run: + +.. code-block:: shell + + git clone https://github.com/ucb-bar/chipyard.git + cd chipyard + ./scripts/init-submodules-no-riscv-tools.sh + +This will have initialized submodules and installed the RISC-V tools and +other dependencies. + +Installing the RISC-V Tools +------------------------------------------- + +We need to install the RISC-V toolchain in order to be able to run RISC-V programs using the Chipyard infrastructure. +This will take about 20-30 minutes. You can expedite the process by setting a ``make`` environment variable to use parallel cores: ``export MAKEFLAGS=-j8``. +TO build the toolchains, you should run: + +:: + + ./scripts/build-toolchains.sh + +.. Note:: If you are planning to use the Hwacha vector unit, or other RoCC-based accelerators, you should build the esp-tools toolchains by adding the ``esp-tools`` argument to the script above. + If you are running on an Amazon Web Services EC2 instance, intending to use FireSim, you can also use the ``--ec2fast`` flag for an expediated installation of a pre-compiled toolchain. + + +What's Next? +------------------------------------------- + +This depends on what you are planning to do with Chipyard. +- If you want to learn about the structure of Chipyard, go to <>. +- If you intend to build one of the vanilla Chipyard examples, go to <> and follow the instructions. +- If you intend to add a new accelerator, go to <> and follow the instructions. +- If you intend to run a simulation of one of the vanilla Chipyard examples, go to :ref:`sw-rtl-sim-intro` and follow the instructions. +- If you intend to run a simulation of a custom Chipyard SoC Configuration, go to <> and follow the instructions. +- If you intend to run a full-system FireSim simulation, go to :ref:`firesim-sim-intro` and follow the instructions. +- If you intend to run a VLSI flow using one of the vanilla Chipyard examples, go to <> and follow the instructions. diff --git a/docs/Simulation/FPGA-Accelerated-Simulators.rst b/docs/Simulation/FPGA-Accelerated-Simulators.rst index 6dab6378..ed13d629 100644 --- a/docs/Simulation/FPGA-Accelerated-Simulators.rst +++ b/docs/Simulation/FPGA-Accelerated-Simulators.rst @@ -1,3 +1,5 @@ +.. _firesim-sim-intro: + FPGA-Accelerated Simulators ============================== @@ -50,8 +52,37 @@ cannot build a FireSim simulator from any generator project in Chipyard except ` which properly invokes MIDAS on the target RTL. In the interim, workaround this limitation by importing Config and Module -classes from other generator projects into FireChip. You should then be able to -refer to those classes or an alias of them in your ``DESIGN`` or ``TARGET_CONFIG`` +classes from other generator projects into FireChip. For example, assuming you Chipyard +config looks as following: + +.. code-block:: scala + class CustomConfig extends Config( + new WithInclusiveCache ++ + new myproject.MyCustomConfig ++ + new DefaultRocketConfig + ) + +Then the equivalent FireChip config (in `generators/firechip/src/main/scala/TargetConfigs.scala`) based on `FireSimRocketChipConfig` +will look as follows: + +.. code-block:: scala + class FireSimCustomConfig extends Config( + new WithBootROM ++ + new WithPeripheryBusFrequency(BigInt(3200000000L)) ++ + new WithExtMemSize(0x400000000L) ++ // 16GB + new WithoutTLMonitors ++ + new WithUARTKey ++ + new WithNICKey ++ + new WithBlockDevice ++ + new WithRocketL2TLBs(1024) ++ + new WithPerfCounters ++ + new WithoutClockGating ++ + new WithInclusiveCache ++ + new myproject.MyCustomConfig ++ + new freechips.rocketchip.system.DefaultConfig) + + +You should then be able to refer to those classes or an alias of them in your ``DESIGN`` or ``TARGET_CONFIG`` variables. Note that if your target machine has I/O not provided in the default FireChip targets (see ``generators/firechip/src/main/scala/Targets.scala``) you may need to write a custom endpoint. diff --git a/docs/Simulation/Software-RTL-Simulators.rst b/docs/Simulation/Software-RTL-Simulators.rst index cef1b1f3..89bd337c 100644 --- a/docs/Simulation/Software-RTL-Simulators.rst +++ b/docs/Simulation/Software-RTL-Simulators.rst @@ -1,3 +1,5 @@ +.. _sw-rtl-sim-intro: + Software RTL Simulators =================================== diff --git a/docs/index.rst b/docs/index.rst index b2fa001a..6a918039 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,14 +8,18 @@ Welcome to Chipyard's documentation! Chipyard is a a framework for designing and evaluating full-system hardware using agile teams. It is composed of a collection of tools and libraries designed to provide an intergration between open-source and commercial tools for the development of systems-on-chip. -New to Chipyard? Jump to the :ref:`Getting Started` page for more info. +New to Chipyard? Jump to the :ref:`Chipyard Basics` page for more info. + + +.. include:: Quick-Start.rst + .. toctree:: :maxdepth: 3 :caption: Contents: :numbered: - Getting-Started/index + Chipyard-Basics/index :maxdepth: 3 :caption: Simulation: @@ -38,9 +42,9 @@ New to Chipyard? Jump to the :ref:`Getting Started` page for more info. VLSI/index :maxdepth: 3 - :caption: Advanced Usage: + :caption: Customization: :numbered: - Advanced-Usage/index + Customization/index Indices and tables ==================