docs reorg

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

docs/Chipyard-Basics/Building-A-Chip.rst

@@ -0,0 +1,3 @@
+Building A Chip
+==============================
+TODO

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -1,4 +1,4 @@
-Chipyard Basics
+Chipyard Components
 ===============================
 
 Generators

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.

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

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

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)

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

docs/Getting-Started/index.rst

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

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.  

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.

docs/Simulation/Software-RTL-Simulators.rst

@@ -1,3 +1,5 @@
+.. _sw-rtl-sim-intro:
+
 Software RTL Simulators
 ===================================
 

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