diff --git a/docs/Advanced-Usage/Resources.rst b/docs/Advanced-Usage/Resources.rst new file mode 100644 index 00000000..538c43b0 --- /dev/null +++ b/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) diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst index 1f313e60..2a8824b2 100644 --- a/docs/Advanced-Usage/index.rst +++ b/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 diff --git a/docs/Chipyard-Basics/Building-A-Chip.rst b/docs/Chipyard-Basics/Building-A-Chip.rst new file mode 100644 index 00000000..dc2d37ce --- /dev/null +++ b/docs/Chipyard-Basics/Building-A-Chip.rst @@ -0,0 +1,5 @@ +.. _build-a-chip: + +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..49aff86a 100644 --- a/docs/Getting-Started/Chipyard-Basics.rst +++ b/docs/Chipyard-Basics/Chipyard-Components.rst @@ -1,4 +1,6 @@ -Chipyard Basics +.. _chipyard-components: + +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..0b688ea6 100644 --- a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst +++ b/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 ------------------ 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..26589204 --- /dev/null +++ b/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. 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/VLSI/HAMMER.rst b/docs/VLSI/HAMMER.rst index a206fe93..c0c77824 100644 --- a/docs/VLSI/HAMMER.rst +++ b/docs/VLSI/HAMMER.rst @@ -1,7 +1,58 @@ -HAMMER +Core HAMMER ================================ `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 `__ and see the `GitHub repository `__. + +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`` 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_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 ``..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 ``HammerTool``, 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 `__. diff --git a/docs/VLSI/index.rst b/docs/VLSI/index.rst index 464d9828..f8bdb7a8 100644 --- a/docs/VLSI/index.rst +++ b/docs/VLSI/index.rst @@ -1,11 +1,11 @@ -VLSI Production +VLSI Flow ================================ -The Chipyard framework aim to provide wrappers to a general VLSI flow. -In particular, we aim to support the HAMMER flow. +The Chipyard framework aims to provide wrappers for a general VLSI flow. +In particular, we aim to support the HAMMER physical design generator flow. .. toctree:: :maxdepth: 2 - :caption: VLSI Production: + :caption: VLSI Flow: HAMMER diff --git a/docs/index.rst b/docs/index.rst index b2fa001a..c44f118f 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: @@ -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 ==================