Merge pull request #178 from ucb-bar/alon-docs-dev

Docs Re-Organization and Edits

docs/Advanced-Usage/Resources.rst

@@ -0,0 +1,38 @@
+Accessing Scala Resources
+===============================
+
+A simple way to copy over a source file to the build directory to be used for a simulation compile or VLSI flow is to use the ``setResource`` or ``addResource`` functions given by FIRRTL.
+They can be used in the following way:
+
+.. code-block:: scala
+
+    class SimSerial(w: Int) extends BlackBox with HasBlackBoxResource {
+      val io = IO(new Bundle {
+        val clock = Input(Clock())
+        val reset = Input(Bool())
+        val serial = Flipped(new SerialIO(w))
+        val exit = Output(Bool())
+      })
+
+      setResource("/testchipip/vsrc/SimSerial.v")
+      setResource("/testchipip/csrc/SimSerial.cc")
+    }
+
+In this example, the ``SimSerial`` files will be copied from a specific folder (in this case the ``path/to/testchipip/src/main/resources/testchipip/...``) to the build folder.
+The ``set/addResource`` path retrieves resources from the ``src/main/resources`` directory.
+So to get an item at ``src/main/resources/fileA.v`` you can use ``setResource("/fileA.v")``.
+However, one caveat of this approach is that to retrieve the file during the FIRRTL compile, you must have that project in the FIRRTL compiler's classpath.
+Thus, you need to add the SBT project as a dependency to the FIRRTL compiler in the Chipyard ``build.sbt``, which in Chipyards case is the ``tapeout`` project.
+For example, you added a new project called ``myAwesomeAccel`` in the Chipyard ``build.sbt``.
+Then you can add it as a ``dependsOn`` dependency to the ``tapeout`` project.
+For example:
+
+.. code-block:: scala
+
+    lazy val myAwesomeAccel = (project in file("generators/myAwesomeAccelFolder"))
+      .dependsOn(rocketchip)
+      .settings(commonSettings)
+
+    lazy val tapeout = conditionalDependsOn(project in file("./tools/barstools/tapeout/"))
+      .dependsOn(myAwesomeAccel)
+      .settings(commonSettings)

docs/Advanced-Usage/index.rst

@@ -6,7 +6,7 @@ They expect you to know about Chisel, Parameters, Configs, etc.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Getting Started:
+   :caption: Advanced Usage:
 
-   Heterogeneous-SoCs
    DTM-Debugging
+   Resources

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

@@ -0,0 +1,5 @@
+.. _build-a-chip:
+
+Building A Chip
+==============================
+TODO

docs/Chipyard-Basics/Chipyard-Components.rst

@@ -1,4 +1,6 @@
-Chipyard Basics
+.. _chipyard-components:
+
+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
+    git clone https://github.com/ucb-bar/chipyard.git
-    cd project-template
+    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

@@ -1,3 +1,5 @@
+.. _adding-an-accelerator:
+
 Adding An Accelerator/Device
 ===============================
 
@@ -49,7 +51,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 +64,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,42 @@
+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 the git submodules.
+
+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 expedited 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 :ref:`chipyard-components`.
+- If you intend to build one of the vanilla Chipyard examples, go to :ref:`build-a-chip` and follow the instructions.
+- If you intend to add a new accelerator, go to :ref:`adding-an-accelerator` 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
+classes from other generator projects into FireChip. For example, assuming you Chipyard 
-refer to those classes or an alias of them in  your ``DESIGN`` or ``TARGET_CONFIG``
+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/VLSI/HAMMER.rst

@@ -1,7 +1,58 @@
-HAMMER
+Core HAMMER
 ================================
 
 `HAMMER <https://github.com/ucb-bar/hammer>`__ is a physical design generator that wraps around vendor specific technologies and tools to provide a single API to create ASICs.
 HAMMER allows for reusability in ASIC design while still providing the designers leeway to make their own modifications.
 
 For more information, read the `HAMMER paper <https://people.eecs.berkeley.edu/~edwardw/pubs/hammer-woset-2018.pdf>`__ and see the `GitHub repository <https://github.com/ucb-bar/hammer>`__.
+
+Actions
+-------
+
+Actions are the top-level tasks Hammer is capable of executing (e.g. synthesis, place-and-route, etc.)
+
+Steps
+-------
+
+Steps are the sub-components of actions that individually addressable in Hammer (e.g. placement in the place-and-route action).
+
+Hooks
+-------
+
+Hooks are modifications to steps or actions that are programmatically defined in a Hammer configuration.
+
+Tool Plugins
+============
+
+Hammer supports separately managed plugins for different CAD tool vendors.
+The types of tools (in there hammer names) supported currently include:
+
+* synthesis
+* par
+* drc
+* lvs
+* sram_generator
+* pcb
+
+In order to configure your tool plugin of choice, you will need to set several configuration variables.
+First, you should select which specific tool you want to use by setting ``vlsi.core.<tool_type>_tool`` to the name of your tool.
+For example ``vlsi.core.par_tool: "innovus"``.
+You will also need to point hammer to the folder that contains your tool plugin by setting ``vlsi.core.<tool_type>_tool_path``.
+This directory should include a folder with the name of the tool as specified previously, which itself includes a python file ``__init__.py`` and a yaml file ``defaults.yml`` specifying the default values for any tool specific variables.
+In addition you can also customize the version of the tools you use by setting ``<tool_type>.<tool_name>.version`` to a tool specific string.
+Looking at the tools ``defaults.yml`` will inform you if there are other variables you would like to set for your use of this tool.
+
+The ``__init__.py`` file should contain a variable, ``tool``, that points to the class implementing this tools Hammer support.
+This class should be a subclass of ``Hammer<tool_type>Tool``, which will be a subclass of ``HammerTool``.
+
+Technology Plugins
+==================
+
+Hammer supports separately managed plugins for different technologies.
+
+Configuration
+=============
+
+To configure a hammer flow the user needs to supply a yaml or json configuration file the chooses the tool and technology plugins and versions as well as any design specific configuration APIs.
+
+You can see the current set of all available Hammer APIs `here <https://github.com/ucb-bar/hammer/blob/master/src/hammer-vlsi/defaults.yml>`__.

docs/VLSI/index.rst

@@ -1,11 +1,11 @@
-VLSI Production
+VLSI Flow
 ================================
 
-The Chipyard framework aim to provide wrappers to a general VLSI flow.
+The Chipyard framework aims to provide wrappers for a general VLSI flow.
-In particular, we aim to support the HAMMER flow.
+In particular, we aim to support the HAMMER physical design generator flow.
 
 .. toctree::
    :maxdepth: 2
-   :caption: VLSI Production:
+   :caption: VLSI Flow:
 
    HAMMER

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:
@@ -37,11 +41,18 @@ New to Chipyard? Jump to the :ref:`Getting Started` page for more info.
    :numbered:
    VLSI/index
 
+   :maxdepth: 3
+   :caption: Customization:
+   :numbered:
+   Customization/index
+
    :maxdepth: 3
    :caption: Advanced Usage:
    :numbered:
    Advanced-Usage/index
 
+
+
 Indices and tables
 ==================