From 19e092b26a1a1aeb566ebb537859e02f0dd21ead Mon Sep 17 00:00:00 2001 From: Jerry Zhao Date: Sat, 1 Jun 2019 15:14:25 -0700 Subject: [PATCH 01/15] Bump boom --- generators/boom | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/generators/boom b/generators/boom index 2f8c419f..0246aceb 160000 --- a/generators/boom +++ b/generators/boom @@ -1 +1 @@ -Subproject commit 2f8c419ff8fa7d848d0d92d4977885cb1e1fa5b3 +Subproject commit 0246aceb0443531a5f0d6525afcbe5fbe15b7c1d From eb93ace725e7db0324f16ddea85dc78d79436a0c Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Sun, 2 Jun 2019 23:25:51 -0700 Subject: [PATCH 02/15] check if commit is on master --- .circleci/check-commit.sh | 40 +++++++++++++++++++++++++++++++++++++++ .circleci/config.yml | 19 +++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100755 .circleci/check-commit.sh diff --git a/.circleci/check-commit.sh b/.circleci/check-commit.sh new file mode 100755 index 00000000..7b0ec9e5 --- /dev/null +++ b/.circleci/check-commit.sh @@ -0,0 +1,40 @@ +#!/bin/bash + +# check to see that submodule commits are present on the master branch + +# turn echo on and error on earliest command +set -ex + +# enter bhd repo +cd $HOME/project + +# initialize submodules and get the hashes +git submodule update --init +status=$(git submodule status) + +search () { + for submodule in "${submodules[@]}" + do + echo "Running check on submodule $submodule in $dir" + hash=$(echo "$status" | grep $submodule | awk '{print$1}' | grep -o "[[:alnum:]]*") + echo "Searching for $hash in origin/master of $submodule" + git -C $dir/$submodule log origin/master | grep "$hash" # needs init'ed submodules + done +} + +submodules=("boom" "hwacha" "rocket-chip" "sifive-blocks" "testchipip") +dir="generators" + +search + +submodules=("esp-tools" "riscv-tools") +dir="toolchains" + +search + +submodules=("barstools" "chisel3" "firrtl" "torture") +dir="tools" + +search + +echo "Done checking all submodules" diff --git a/.circleci/config.yml b/.circleci/config.yml index d2354fde..0f982233 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -5,6 +5,22 @@ version: 2 # set of jobs to run jobs: + commit-on-master-check: + docker: + - image: riscvboom/riscvboom-images:0.0.5 + environment: + JVM_OPTS: -Xmx3200m # Customize the JVM maximum heap limit + TERM: dumb + + steps: + # Checkout the code + - checkout + + - run: + name: Check commits of each submodule + command: | + .circleci/check-commit.sh + install-riscv-toolchain: docker: - image: riscvboom/riscvboom-images:0.0.5 @@ -470,6 +486,9 @@ workflows: version: 2 build-and-test-rebar-integration: jobs: + # check to make sure commits are on master + - commit-on-master-check + # Make the toolchains - install-riscv-toolchain From bbaa8d58b058c76c10a4457c18e3a84b2a6a19ac Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Mon, 3 Jun 2019 09:41:56 -0700 Subject: [PATCH 03/15] switch to git branch --- .circleci/check-commit.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.circleci/check-commit.sh b/.circleci/check-commit.sh index 7b0ec9e5..ea7e30f5 100755 --- a/.circleci/check-commit.sh +++ b/.circleci/check-commit.sh @@ -18,7 +18,7 @@ search () { echo "Running check on submodule $submodule in $dir" hash=$(echo "$status" | grep $submodule | awk '{print$1}' | grep -o "[[:alnum:]]*") echo "Searching for $hash in origin/master of $submodule" - git -C $dir/$submodule log origin/master | grep "$hash" # needs init'ed submodules + git -C $dir/$submodule branch -r --contains "$hash" | grep "origin/master" # needs init'ed submodules done } From 51960f4345e23fe7365301944c31d40d9fc07116 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Mon, 3 Jun 2019 19:11:45 -0700 Subject: [PATCH 04/15] remove deprecated CHISEL_ARGS --- common.mk | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/common.mk b/common.mk index f7e46608..ff67066a 100644 --- a/common.mk +++ b/common.mk @@ -37,11 +37,9 @@ $(sim_dotf): $(call lookup_scala_srcs,$(base_dir)/generators/utilities/src/main/ ######################################################################################### # create firrtl file rule and variables ######################################################################################### -CHISEL_ARGS ?= - $(FIRRTL_FILE) $(ANNO_FILE): $(SCALA_SOURCES) $(sim_dotf) mkdir -p $(build_dir) - cd $(base_dir) && $(SBT) "project $(SBT_PROJECT)" "runMain $(GENERATOR_PACKAGE).Generator $(CHISEL_ARGS) $(build_dir) $(MODEL_PACKAGE) $(MODEL) $(CONFIG_PACKAGE) $(CONFIG)" + cd $(base_dir) && $(SBT) "project $(SBT_PROJECT)" "runMain $(GENERATOR_PACKAGE).Generator $(build_dir) $(MODEL_PACKAGE) $(MODEL) $(CONFIG_PACKAGE) $(CONFIG)" ######################################################################################### # create verilog files rules and variables From af8f0b0507efa547be5062cd9203173ddaac5df5 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Mon, 10 Jun 2019 13:56:38 -0700 Subject: [PATCH 05/15] update naming in accordance with boom --- generators/example/src/main/scala/Top.scala | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/generators/example/src/main/scala/Top.scala b/generators/example/src/main/scala/Top.scala index 5ee73906..a3fa99f8 100644 --- a/generators/example/src/main/scala/Top.scala +++ b/generators/example/src/main/scala/Top.scala @@ -16,13 +16,13 @@ import sifive.blocks.devices.gpio._ // BOOM and/or Rocket Top Level Systems // ------------------------------- -class BoomRocketTop(implicit p: Parameters) extends boom.system.ExampleBoomAndRocketSystem +class BoomRocketTop(implicit p: Parameters) extends boom.system.BoomRocketSystem with HasNoDebug with HasPeripherySerial { override lazy val module = new BoomRocketTopModule(this) } -class BoomRocketTopModule[+L <: BoomRocketTop](l: L) extends boom.system.ExampleBoomAndRocketSystemModule(l) +class BoomRocketTopModule[+L <: BoomRocketTop](l: L) extends boom.system.BoomRocketSystemModule(l) with HasNoDebugModuleImp with HasPeripherySerialModuleImp with DontTouch From a906f05962042e413c1d2ddd0747e51f511079cc Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Tue, 11 Jun 2019 17:55:32 -0700 Subject: [PATCH 06/15] use hart0 for the test suite --- generators/example/src/main/scala/Generator.scala | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/generators/example/src/main/scala/Generator.scala b/generators/example/src/main/scala/Generator.scala index c5df8cb1..684b2834 100644 --- a/generators/example/src/main/scala/Generator.scala +++ b/generators/example/src/main/scala/Generator.scala @@ -57,11 +57,11 @@ object Generator extends GeneratorApp { import freechips.rocketchip.system.DefaultTestSuites._ val xlen = params(XLen) - // TODO: for now only generate tests for the first rocket/boom tile in the subsystem // TODO: support heterogenous systems? + // TODO: generate tests for hart0 of the system since asm tests run on hart0 by default // rocket specific tests - params(RocketTilesKey).headOption.map { tileParams => + params(RocketTilesKey).find(_.hartId == 0).map { tileParams => val coreParams = tileParams.core val vm = coreParams.useVM val env = if (vm) List("p","v") else List("p") @@ -95,7 +95,7 @@ object Generator extends GeneratorApp { } // boom specific tests - params(BoomTilesKey).headOption.map { tileParams => + params(BoomTilesKey).find(_.hartId == 0).map { tileParams => val coreParams = tileParams.core val vm = coreParams.useVM val env = if (vm) List("p","v") else List("p") From ba6352afca7c0b873d5fcfbac0142020b4e7cc4b Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 12 Jun 2019 14:25:32 -0700 Subject: [PATCH 07/15] update boom hash --- generators/boom | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/generators/boom b/generators/boom index 0246aceb..22c5f9ec 160000 --- a/generators/boom +++ b/generators/boom @@ -1 +1 @@ -Subproject commit 0246aceb0443531a5f0d6525afcbe5fbe15b7c1d +Subproject commit 22c5f9ec3f0325b9bdbf1a98b5752b6ac843eb19 From 4a667c3df94a9e6309e09ad207677ec5d1b74944 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 12 Jun 2019 14:54:49 -0700 Subject: [PATCH 08/15] correct naming in defaults --- variables.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/variables.mk b/variables.mk index f3fc05b1..76632f48 100644 --- a/variables.mk +++ b/variables.mk @@ -48,7 +48,7 @@ ifeq ($(SUB_PROJECT),boom) CONFIG_PACKAGE ?= boom.system GENERATOR_PACKAGE ?= boom.system TB ?= TestDriver - TOP ?= ExampleBoomAndRocketSystem + TOP ?= BoomRocketSystem endif # for Rocket-chip developers ifeq ($(SUB_PROJECT),rocketchip) From 4cca0ed57e5a9751f7d31940743e6fcfb07f88bb Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Wed, 19 Jun 2019 09:35:46 -0700 Subject: [PATCH 09/15] bump verilator version --- sims/verisim/verilator.mk | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sims/verisim/verilator.mk b/sims/verisim/verilator.mk index a5c953c1..4edfa6e3 100644 --- a/sims/verisim/verilator.mk +++ b/sims/verisim/verilator.mk @@ -5,7 +5,7 @@ ######################################################################################### # verilator version, binary, and path ######################################################################################### -VERILATOR_VERSION=4.008 +VERILATOR_VERSION=4.016 VERILATOR_SRCDIR=verilator/src/verilator-$(VERILATOR_VERSION) INSTALLED_VERILATOR=$(abspath verilator/install/bin/verilator) @@ -15,7 +15,7 @@ INSTALLED_VERILATOR=$(abspath verilator/install/bin/verilator) $(INSTALLED_VERILATOR): $(VERILATOR_SRCDIR)/bin/verilator $(MAKE) -C $(VERILATOR_SRCDIR) installbin installdata touch $@ - + .PHONY: verilator_install: $(INSTALLED_VERILATOR) From b556bee0b9a1500cad165033f56990db9ab3a824 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 21 Jun 2019 11:28:35 -0700 Subject: [PATCH 10/15] rename to "Chipyard" --- .circleci/README.md | 12 ++++++------ .circleci/build-toolchains.sh | 2 +- .circleci/config.yml | 2 +- README.md | 16 ++++++++-------- build.sbt | 16 ++++++++-------- common.mk | 6 +++--- docs/Generators/index.rst | 2 +- .../Adding-An-Accelerator-Tutorial.rst | 6 +++--- .../{REBAR-Basics.rst => Chipyard-Basics.rst} | 6 +++--- ...-mixins.rst => Chipyard-Generator-Mixins.rst} | 0 .../Configs-Parameters-Mixins.rst | 4 ++-- docs/Getting-Started/Development-Ecosystem.rst | 6 +++--- docs/Getting-Started/Running-A-Simulation.rst | 6 +++--- docs/Getting-Started/index.rst | 6 +++--- docs/Makefile | 2 +- docs/Simulation/Commercial-Simulators.rst | 2 +- docs/Simulation/FPGA-Based-Simulators.rst | 4 ++-- docs/Simulation/Open-Source-Simulators.rst | 2 +- docs/Simulation/index.rst | 4 ++-- docs/Tools/index.rst | 2 +- docs/VLSI/index.rst | 2 +- docs/conf.py | 14 +++++++------- docs/index.rst | 8 ++++---- scripts/build-toolchains.sh | 6 +++--- scripts/gen-tags.sh | 4 ++-- variables.mk | 8 ++++---- 26 files changed, 74 insertions(+), 74 deletions(-) rename docs/Getting-Started/{REBAR-Basics.rst => Chipyard-Basics.rst} (97%) rename docs/Getting-Started/{rebar-generator-mixins.rst => Chipyard-Generator-Mixins.rst} (100%) diff --git a/.circleci/README.md b/.circleci/README.md index 50ede340..018b4b57 100644 --- a/.circleci/README.md +++ b/.circleci/README.md @@ -1,5 +1,5 @@ -REBAR CI -======== +Chipyard CI +=========== Website: https://circleci.com/gh/ucb-bar/project-template @@ -32,17 +32,17 @@ Here the key is built from a string where the `checksum` portion converts the fi .circleci directory ------------------- -This directory contains all the collateral for the REBAR CI to work. +This directory contains all the collateral for the Chipyard CI to work. The following is included: - + build-toolchains.sh # build either riscv-tools or esp-tools build-verilator.sh # build verilator create-hash.sh # create hashes of riscv-tools/esp-tools so circleci caching can work do-rtl-build.sh # use verilator to build a sim executable config.yml # main circleci config script to enumerate jobs/workflows -How things are setup for REBAR ------------------------------- +How things are setup for Chipyard +--------------------------------- The steps for CI to run are as follows. 1st, build the toolchains in parallel (note: `esp-tools` is currently not used in the run). diff --git a/.circleci/build-toolchains.sh b/.circleci/build-toolchains.sh index 28b87caa..9b5477f6 100755 --- a/.circleci/build-toolchains.sh +++ b/.circleci/build-toolchains.sh @@ -11,5 +11,5 @@ if [ ! -d "$HOME/$1-install" ]; then cd $HOME/ # init all submodules including the tools - REBAR_DIR=$HOME/project ./project/scripts/build-toolchains.sh $1 + CHIPYARD_DIR=$HOME/project ./project/scripts/build-toolchains.sh $1 fi diff --git a/.circleci/config.yml b/.circleci/config.yml index 0f982233..61e73e54 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -484,7 +484,7 @@ jobs: # Order and dependencies of jobs to run workflows: version: 2 - build-and-test-rebar-integration: + build-and-test-chipyard-integration: jobs: # check to make sure commits are on master - commit-on-master-check diff --git a/README.md b/README.md index 2bf6a212..708de178 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,20 @@ -# REBAR Framework [![CircleCI](https://circleci.com/gh/ucb-bar/project-template/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/project-template/tree/master) +# Chipyard Framework [![CircleCI](https://circleci.com/gh/ucb-bar/project-template/tree/master.svg?style=svg)](https://circleci.com/gh/ucb-bar/project-template/tree/master) -## Using REBAR +## Using Chipyard -To get started using REBAR, see the documentation on the REBAR documentation site: https://bar-project-template.readthedocs.io/en/latest/ +To get started using Chipyard, see the documentation on the Chipyard documentation site: https://bar-project-template.readthedocs.io/en/latest/ -## What is REBAR +## What is Chipyard -REBAR is an open source starter template for your custom Chisel project. +Chipyard is an open source starter template for your custom Chisel project. It will allow you to leverage the Chisel HDL, Rocket Chip SoC generator, and other [Berkeley][berkeley] projects to produce a [RISC-V][riscv] SoC with everything from MMIO-mapped peripherals to custom accelerators. It contains processor cores ([Rocket][rocket-chip], [BOOM][boom]), accelerators ([Hwacha][hwacha]), FPGA simulation tools ([FireSim][firesim]), ASIC tools ([HAMMER][hammer]) and other tooling to help create a full featured SoC. -REBAR is actively developed in the [Berkeley Architecture Research Group][ucb-bar] in the [Electrical Engineering and Computer Sciences Department][eecs] at the [University of California, Berkeley][berkeley]. +Chipyard is actively developed in the [Berkeley Architecture Research Group][ucb-bar] in the [Electrical Engineering and Computer Sciences Department][eecs] at the [University of California, Berkeley][berkeley]. ## Resources -* REBAR Website: ...TBD at a later date... -* REBAR Documentation: https://bar-project-template.readthedocs.io/ +* Chipyard Website: ...TBD at a later date... +* Chipyard Documentation: https://bar-project-template.readthedocs.io/ [hwacha]:http://hwacha.org [hammer]:https://github.com/ucb-bar/hammer diff --git a/build.sbt b/build.sbt index 6a06fcba..09c78b34 100644 --- a/build.sbt +++ b/build.sbt @@ -19,17 +19,17 @@ lazy val commonSettings = Seq( Resolver.sonatypeRepo("releases"), Resolver.mavenLocal)) -lazy val rebarFirrtl = (project in file("tools/firrtl")) +lazy val chipyardFirrtl = (project in file("tools/firrtl")) .settings(commonSettings) lazy val rocketchip = RootProject(file("generators/rocket-chip")) -lazy val rebarrocketchip = project +lazy val chipyardrocketchip = project .dependsOn(rocketchip) .settings(commonSettings) lazy val testchipip = (project in file("generators/testchipip")) - .dependsOn(rebarrocketchip) + .dependsOn(chipyardrocketchip) .settings(commonSettings) // Checks for -DROCKET_USE_MAVEN. @@ -53,25 +53,25 @@ lazy val utilities = conditionalDependsOn(project in file("generators/utilities" .settings(commonSettings) lazy val hwacha = (project in file ("generators/hwacha")) - .dependsOn(rebarrocketchip) + .dependsOn(chipyardrocketchip) .settings(commonSettings) lazy val boom = (project in file("generators/boom")) - .dependsOn(rebarrocketchip) + .dependsOn(chipyardrocketchip) .settings(commonSettings) lazy val tapeout = conditionalDependsOn(project in file("./tools/barstools/tapeout/")) - .dependsOn(rebarFirrtl) + .dependsOn(chipyardFirrtl) .settings(commonSettings) lazy val mdf = (project in file("./tools/barstools/mdf/scalalib/")) .settings(commonSettings) lazy val `barstools-macros` = (project in file("./tools/barstools/macros/")) - .dependsOn(mdf, rebarrocketchip, rebarFirrtl) + .dependsOn(mdf, chipyardrocketchip, chipyardFirrtl) .enablePlugins(sbtassembly.AssemblyPlugin) .settings(commonSettings) lazy val sifive_blocks = (project in file("generators/sifive-blocks")) - .dependsOn(rebarrocketchip) + .dependsOn(chipyardrocketchip) .settings(commonSettings) diff --git a/common.mk b/common.mk index ff67066a..bd61184b 100644 --- a/common.mk +++ b/common.mk @@ -22,10 +22,10 @@ TESTCHIPIP_CLASSES ?= "$(TESTCHIP_DIR)/target/scala-$(SCALA_VERSION_MAJOR)/class ######################################################################################### FIRRTL_JAR ?= $(ROCKETCHIP_DIR)/lib/firrtl.jar -$(FIRRTL_JAR): $(call lookup_scala_srcs, $(REBAR_FIRRTL_DIR)/src/main/scala) - $(MAKE) -C $(REBAR_FIRRTL_DIR) SBT="$(SBT)" root_dir=$(REBAR_FIRRTL_DIR) build-scala +$(FIRRTL_JAR): $(call lookup_scala_srcs, $(CHIPYARD_FIRRTL_DIR)/src/main/scala) + $(MAKE) -C $(CHIPYARD_FIRRTL_DIR) SBT="$(SBT)" root_dir=$(CHIPYARD_FIRRTL_DIR) build-scala mkdir -p $(dir $@) - cp -p $(REBAR_FIRRTL_DIR)/utils/bin/firrtl.jar $@ + cp -p $(CHIPYARD_FIRRTL_DIR)/utils/bin/firrtl.jar $@ touch $@ ######################################################################################### diff --git a/docs/Generators/index.rst b/docs/Generators/index.rst index 765b2549..a01b5adc 100644 --- a/docs/Generators/index.rst +++ b/docs/Generators/index.rst @@ -5,7 +5,7 @@ Generator can be thought of as a generalized RTL design, written using a mix of This type of meta-programming is enabled by the Chisel hardware description language (see :ref:`Chisel`). A standard RTL design is essentially just a single instance of a design coming from a generator. However, by using meta-programming and parameter systems, generators can allow for integration of complex hardware designs in automated ways. -The following pages introduce the generators integrated with the REBAR framework. +The following pages introduce the generators integrated with the Chipyard framework. .. toctree:: :maxdepth: 2 diff --git a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst b/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst index bad5ceef..4eefe9b8 100644 --- a/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst +++ b/docs/Getting-Started/Adding-An-Accelerator-Tutorial.rst @@ -28,7 +28,7 @@ Integrating into the Generator Build System ------------------------------------------- While developing, you want to include Chisel code in a submodule so that it can be shared by different projects. -To add a submodule to the REBAR framework, make sure that your project is organized as follows. +To add a submodule to the Chipyard framework, make sure that your project is organized as follows. .. code-block:: none @@ -45,7 +45,7 @@ Then add it as a submodule to under the following directory hierarchy: ``generat cd generators/ git submodule add https://git-repository.com/yourproject.git -Then add ``yourproject`` to the REBAR top-level build.sbt file. +Then add ``yourproject`` to the Chipyard top-level build.sbt file. .. code-block:: scala @@ -59,7 +59,7 @@ the ``example`` project, change the final line in build.sbt to the following. lazy val example = (project in file(".")).settings(commonSettings).dependsOn(testchipip, yourproject) -Finally, add ``yourproject`` to the ``PACKAGES`` variable in the ``common.mk`` file in the REBAR top level. +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. MMIO Peripheral diff --git a/docs/Getting-Started/REBAR-Basics.rst b/docs/Getting-Started/Chipyard-Basics.rst similarity index 97% rename from docs/Getting-Started/REBAR-Basics.rst rename to docs/Getting-Started/Chipyard-Basics.rst index 5dcac5d7..7b9f1bbe 100644 --- a/docs/Getting-Started/REBAR-Basics.rst +++ b/docs/Getting-Started/Chipyard-Basics.rst @@ -1,10 +1,10 @@ -REBAR Basics +Chipyard Basics =============================== Generators ------------------------------------------- -The REBAR Framework currently consists of the following RTL generators: +The Chipyard Framework currently consists of the following RTL generators: Processor Cores ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -72,7 +72,7 @@ Toolchains A collection of software toolchains used to develop and execute software on the RISC-V ISA. The include compiler and assembler toolchains, functional ISA simulator (spike), the Berkeley Boot Loader (BBL) and proxy kernel. The riscv-tools repository was previously required to run any RISC-V software, however, many of the riscv-tools components have since been upstreamed to their respective open-source projects (Linux, GNU, etc.). - Nevertheless, for consistent versioning, as well as software design flexibility for custom hardware, we include the riscv-tools repository and installation in the REBAR framework. + Nevertheless, for consistent versioning, as well as software design flexibility for custom hardware, we include the riscv-tools repository and installation in the Chipyard framework. **esp-tools** A fork of riscv-tools, designed to work with the Hwacha non-standard RISC-V extension. diff --git a/docs/Getting-Started/rebar-generator-mixins.rst b/docs/Getting-Started/Chipyard-Generator-Mixins.rst similarity index 100% rename from docs/Getting-Started/rebar-generator-mixins.rst rename to docs/Getting-Started/Chipyard-Generator-Mixins.rst diff --git a/docs/Getting-Started/Configs-Parameters-Mixins.rst b/docs/Getting-Started/Configs-Parameters-Mixins.rst index 852f85af..d9becfdf 100644 --- a/docs/Getting-Started/Configs-Parameters-Mixins.rst +++ b/docs/Getting-Started/Configs-Parameters-Mixins.rst @@ -1,7 +1,7 @@ Configs, Parameters, Mix-ins, and Everything In Between ======================================================== -A significant portion of generators in the REBAR framework use the Rocket Chip parameter system. +A significant portion of generators in the Chipyard framework use the Rocket Chip parameter system. This parameter system enables for the flexible configuration of the SoC without invasive RTL changes. In order to use the parameter system correctly, we will use several terms and conventions: @@ -69,7 +69,7 @@ Cake Pattern ------------------------- A cake pattern is a Scala programming pattern, which enable "mixing" of multiple traits or interface definitions (sometimes referred to as dependency injection). -It is used in the Rocket Chip SoC library and REBAR framework in merging multiple system components and IO interfaces into a large system component. +It is used in the Rocket Chip SoC library and Chipyard framework in merging multiple system components and IO interfaces into a large system component. :numref:`cake-example` shows a Rocket Chip based SoC that merges multiple system components (BootROM, UART, etc) into a single top-level design. diff --git a/docs/Getting-Started/Development-Ecosystem.rst b/docs/Getting-Started/Development-Ecosystem.rst index fa407194..7755a7f3 100644 --- a/docs/Getting-Started/Development-Ecosystem.rst +++ b/docs/Getting-Started/Development-Ecosystem.rst @@ -1,12 +1,12 @@ Development Ecosystem =============================== -REBAR Approach +Chipyard Approach ------------------------------------------- The trend towards agile hardware design and evaluation provides an ecosystem of debugging and implementation tools, that make it easier for computer architecture researchers to develop novel concepts. -REBAR hopes to build on this prior work in order to create a singular location to which multiple projects within the `Berkeley Architecture Research `__ can coexist and be used together. -REBAR aims to be the "one-stop shop" for creating and testing your own unique System on a Chip (SoC). +Chipyard hopes to build on this prior work in order to create a singular location to which multiple projects within the `Berkeley Architecture Research `__ can coexist and be used together. +Chipyard aims to be the "one-stop shop" for creating and testing your own unique System on a Chip (SoC). Chisel/FIRRTL ------------------------------------------- diff --git a/docs/Getting-Started/Running-A-Simulation.rst b/docs/Getting-Started/Running-A-Simulation.rst index 673bf0ae..0cc4a024 100644 --- a/docs/Getting-Started/Running-A-Simulation.rst +++ b/docs/Getting-Started/Running-A-Simulation.rst @@ -1,13 +1,13 @@ Running A Simulation ======================================================== -REBAR provides support and integration for multiple simulation flows, for various user levels and requirements. +Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements. In the majority of cases during a digital design development process, simple software RTL simulation is needed. When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution. Software RTL Simulation ------------------------ -The REBAR framework provides wrappers for two common software RTL simulators: +The Chipyard framework provides wrappers for two common software RTL simulators: the open-source Verilator simulator and the proprietary VCS simulator. For more information on either of these simulators, please refer to :ref:`Verilator` or :ref:`VCS`. The following instructions assume at least one of these simulators is installed. @@ -97,7 +97,7 @@ FireSim enables simulations at 1000x-100000x the speed of standard software simu This is enabled using FPGA-acceleration on F1 instances of the AWS (Amazon Web Services) public cloud. Therefore FireSim simulation requires to be set-up on the AWS public cloud rather than on our local development machine. -To run an FPGA-accelerated simulation using FireSim, a we need to clone the REBAR repository (or our fork of the REBAR repository) to an AWS EC2, and follow the setup instructions specified in the FireSim Initial Setup documentation page. +To run an FPGA-accelerated simulation using FireSim, a we need to clone the Chipyard repository (or our fork of the Chipyard repository) to an AWS EC2, and follow the setup instructions specified in the FireSim Initial Setup documentation page. After setting up the FireSim environment, we now need to generate a FireSim simulation around our selected digital design. We will work from within the ``sims/firesim`` directory. diff --git a/docs/Getting-Started/index.rst b/docs/Getting-Started/index.rst index be6aa1e3..dcfe0802 100644 --- a/docs/Getting-Started/index.rst +++ b/docs/Getting-Started/index.rst @@ -1,7 +1,7 @@ Getting Started ================================ -These guides will walk you through the basics of the REBAR framework: +These guides will walk you through the basics of the Chipyard framework: - First, we will go over the different configurations available. @@ -13,9 +13,9 @@ Hit next to get started! :maxdepth: 2 :caption: Getting Started: - REBAR-Basics + Chipyard-Basics Configs-Parameters-Mixins Adding-An-Accelerator-Tutorial Initial-Repo-Setup Running-A-Simulation - rebar-generator-mixins + Chipyard-Generator-Mixins diff --git a/docs/Makefile b/docs/Makefile index b3492e6c..adea9f26 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -4,7 +4,7 @@ # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = python -msphinx -SPHINXPROJ = REBAR +SPHINXPROJ = Chipyard SOURCEDIR = . BUILDDIR = _build diff --git a/docs/Simulation/Commercial-Simulators.rst b/docs/Simulation/Commercial-Simulators.rst index 8c1c34d7..0e971d51 100644 --- a/docs/Simulation/Commercial-Simulators.rst +++ b/docs/Simulation/Commercial-Simulators.rst @@ -6,7 +6,7 @@ VCS `VCS `__ is a commercial RTL simulator developed by Synopsys. It requires commercial licenses. -The REBAR framework can compile and execute simulations using VCS. +The Chipyard framework can compile and execute simulations using VCS. VCS simulation will generally compile faster than Verilator simulations. To run a simulation using VCS, perform the following steps: diff --git a/docs/Simulation/FPGA-Based-Simulators.rst b/docs/Simulation/FPGA-Based-Simulators.rst index 9ef19d49..1180b470 100644 --- a/docs/Simulation/FPGA-Based-Simulators.rst +++ b/docs/Simulation/FPGA-Based-Simulators.rst @@ -9,9 +9,9 @@ FireSim allows RTL-level simulation at orders-of-magnitude faster speeds than so FireSim also provides additional device models to allow full-system simulation, including memory models and network models. FireSim currently supports running only on Amazon EC2 F1 FPGA-enabled virtual instances on the public cloud. -In order to simulate your REBAR design using FireSim, you should follow the following steps: +In order to simulate your Chipyard design using FireSim, you should follow the following steps: Follow the initial EC2 setup instructions as detailed in the `FireSim documentation `__. -Then clone your full REBAR repository onto your Amazon EC2 FireSim manager instance. +Then clone your full Chipyard repository onto your Amazon EC2 FireSim manager instance. Enter the ``sims/FireSim`` directory, and follow the FireSim instructions for `running a simulation `__. diff --git a/docs/Simulation/Open-Source-Simulators.rst b/docs/Simulation/Open-Source-Simulators.rst index 11d8d696..bc8a0dcc 100644 --- a/docs/Simulation/Open-Source-Simulators.rst +++ b/docs/Simulation/Open-Source-Simulators.rst @@ -5,7 +5,7 @@ Verilator ----------------------- `Verilator `__ is an open-source LGPL-Licensed simulator maintained by `Veripool `__. -The REBAR framework can download, build, and execute simulations using Verilator. +The Chipyard framework can download, build, and execute simulations using Verilator. To run a simulation using Verilator, perform the following steps: diff --git a/docs/Simulation/index.rst b/docs/Simulation/index.rst index d61b5ed7..339960bd 100644 --- a/docs/Simulation/index.rst +++ b/docs/Simulation/index.rst @@ -1,10 +1,10 @@ Simulators ======================= -REBAR provides support and integration for multiple simulation flows, for various user levels and requirements. +Chipyard provides support and integration for multiple simulation flows, for various user levels and requirements. In the majority of cases during a digital design development process, a simple software RTL simulation will do. When more advanced full-system evaluation is required, with long running workloads, FPGA-accelerated simulation will then become a preferable solution. -The following pages provide detailed information about the simulation possibilities within the REBAR framework. +The following pages provide detailed information about the simulation possibilities within the Chipyard framework. .. toctree:: :maxdepth: 2 diff --git a/docs/Tools/index.rst b/docs/Tools/index.rst index 37e0d76e..d73d4072 100644 --- a/docs/Tools/index.rst +++ b/docs/Tools/index.rst @@ -1,7 +1,7 @@ Tools ============================== -The REBAR framework relays heavily on a set of Scala-based tools. +The Chipyard framework relays heavily on a set of Scala-based tools. The following pages will introduce them, and how we can use them in order to generate flexible designs. .. toctree:: diff --git a/docs/VLSI/index.rst b/docs/VLSI/index.rst index 448fadd7..464d9828 100644 --- a/docs/VLSI/index.rst +++ b/docs/VLSI/index.rst @@ -1,7 +1,7 @@ VLSI Production ================================ -The REBAR framework aim to provide wrappers to a general VLSI flow. +The Chipyard framework aim to provide wrappers to a general VLSI flow. In particular, we aim to support the HAMMER flow. .. toctree:: diff --git a/docs/conf.py b/docs/conf.py index 9b7bbe43..200e0c1e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- # -# REBAR documentation build configuration file, created by +# Chipyard documentation build configuration file, created by # sphinx-quickstart on Fri Mar 8 11:46:38 2019. # # This file is execfile()d with the current directory set to its @@ -52,7 +52,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'REBAR' +project = u'Chipyard' copyright = u'2019, Berkeley Architecture Research' author = u'Berkeley Architecture Research' @@ -125,7 +125,7 @@ html_sidebars = { # -- Options for HTMLHelp output ------------------------------------------ # Output file base name for HTML help builder. -htmlhelp_basename = 'REBARdoc' +htmlhelp_basename = 'Chipyarddoc' # -- Options for LaTeX output --------------------------------------------- @@ -152,7 +152,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'REBAR.tex', u'REBAR Documentation', + (master_doc, 'Chipyard.tex', u'Chipyard Documentation', u'Berkeley Architecture Research', 'manual'), ] @@ -162,7 +162,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'rebar', u'REBAR Documentation', + (master_doc, 'chipyard', u'Chipyard Documentation', [author], 1) ] @@ -173,8 +173,8 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'REBAR', u'REBAR Documentation', - author, 'REBAR', 'One line description of project.', + (master_doc, 'Chipyard', u'Chipyard Documentation', + author, 'Chipyard', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/index.rst b/docs/index.rst index 68598e7a..ce083f2c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,14 +1,14 @@ -.. REBAR documentation master file, created by +.. Chipyard documentation master file, created by sphinx-quickstart on Fri Mar 8 11:46:38 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to REBAR's documentation! +Welcome to Chipyard's documentation! ================================= -REBAR is a a framework for designing and evaluating full-system hardware using agile teams. +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 REBAR? Jump to the :ref:`Getting Started` page for more info. +New to Chipyard? Jump to the :ref:`Getting Started` page for more info. .. toctree:: :maxdepth: 3 diff --git a/scripts/build-toolchains.sh b/scripts/build-toolchains.sh index 9b659109..20ce4800 100755 --- a/scripts/build-toolchains.sh +++ b/scripts/build-toolchains.sh @@ -6,7 +6,7 @@ set -o pipefail unamestr=$(uname) RDIR=$(pwd) -: ${REBAR_DIR:=$(pwd)} #default value is the PWD unless overridden +: ${CHIPYARD_DIR:=$(pwd)} #default value is the PWD unless overridden if [ $# -ne 0 ]; then TOOLCHAIN=$1 @@ -26,8 +26,8 @@ RISCV="$(pwd)/$INSTALL_DIR" # install risc-v tools export RISCV="$RISCV" -git -C $REBAR_DIR submodule update --init --recursive toolchains/$TOOLCHAIN #--jobs 8 -cd "$REBAR_DIR/toolchains/$TOOLCHAIN" +git -C $CHIPYARD_DIR submodule update --init --recursive toolchains/$TOOLCHAIN #--jobs 8 +cd "$CHIPYARD_DIR/toolchains/$TOOLCHAIN" export MAKEFLAGS="-j16" ./build.sh cd $RDIR diff --git a/scripts/gen-tags.sh b/scripts/gen-tags.sh index 52df9aa7..afc7e228 100755 --- a/scripts/gen-tags.sh +++ b/scripts/gen-tags.sh @@ -1,10 +1,10 @@ #!/usr/bin/env bash -# run this script in the main rebar directory to generate ctags for all relevant repos +# run this script in the main Chipyard directory to generate ctags for all relevant repos # note: this requires exuberant-ctags # tested with: Exuberant Ctags 5.8 # instructions: -# cd /path/to/rebar/ +# cd /path/to/chipyard/ # ./scripts/gen-tags.sh # # input: diff --git a/variables.mk b/variables.mk index 76632f48..601afb03 100644 --- a/variables.mk +++ b/variables.mk @@ -52,7 +52,7 @@ ifeq ($(SUB_PROJECT),boom) endif # for Rocket-chip developers ifeq ($(SUB_PROJECT),rocketchip) - SBT_PROJECT ?= rebarrocketchip + SBT_PROJECT ?= chipyardrocketchip MODEL ?= TestHarness VLOG_MODEL ?= TestHarness MODEL_PACKAGE ?= freechips.rocketchip.system @@ -78,9 +78,9 @@ endif ######################################################################################### # path to rocket-chip and testchipip ######################################################################################### -ROCKETCHIP_DIR = $(base_dir)/generators/rocket-chip -TESTCHIP_DIR = $(base_dir)/generators/testchipip -REBAR_FIRRTL_DIR = $(base_dir)/tools/firrtl +ROCKETCHIP_DIR = $(base_dir)/generators/rocket-chip +TESTCHIP_DIR = $(base_dir)/generators/testchipip +CHIPYARD_FIRRTL_DIR = $(base_dir)/tools/firrtl ######################################################################################### # names of various files needed to compile and run things From 5f19697618b7f42e4c0df54bfc9a4030c83b4f01 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 31 May 2019 17:51:05 -0700 Subject: [PATCH 11/15] first attempt at explaining heter systems --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 127 +++++++++++++++++++++ docs/Advanced-Usage/index.rst | 11 ++ docs/index.rst | 4 + 3 files changed, 142 insertions(+) create mode 100644 docs/Advanced-Usage/Heterogeneous-SoCs.rst create mode 100644 docs/Advanced-Usage/index.rst diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst new file mode 100644 index 00000000..2ee9cba4 --- /dev/null +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -0,0 +1,127 @@ +Heterogeneous SoCs +=============================== + +The REBAR framework involves multiple cores and accelerators that can be composed in arbitrary ways. +This discussion will focus on how you combine Rocket, BOOM and Hwacha in particular ways to create a unique SoC. + +Creating a Rocket and BOOM System +------------------------------------------- + +Instantiating an SoC with Rocket and BOOM cores is all done with the configuration system and two specific mixins. +Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core. +When used together you can create a heterogeneous system. +The following example shows a dual core BOOM with a single Rocket. + +.. code-block:: scala + + class DualCoreBoomAndRocketConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new boom.system.WithRenumberHarts ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +In this example, the ``WithN...Cores(X)`` mixins set up particular parameters for the duplicated core. +For example, the Rocket tiles will be "BigCores" while BOOM has some generic parameters set in its mixin. +In BOOMs case, we override these base core parameters to create multiple "DefaultBoom"s with calling ``DefaultBoomConfig`` after the multi-core instantiation. +This mixin applies to all the BOOM cores in the system and sets up the parameters for each. + +Great! Now you have a heterogeneous setup with BOOMs and Rockets. +The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId``. +This is done with ``WithRenumberHarts`` (which can label the Rocket cores first or the BOOM cores first). +The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only that type of core in the system. +Thus, without the renumber mixin, each set of cores is labeled starting from zero. + +Another option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core. +The mixin to add to your system would look something like the following. + +.. code-block:: scala + + // create 6 cores (4 boom and 2 rocket) + class WithHeterCoresSetup extends Config((site, here, up) => { + case BoomTilesKey => { + val boomTile0 = BoomTileParams(...) // params for boom core 0 + val boomTile1 = BoomTileParams(...) // params for boom core 1 + val boomTile2 = BoomTileParams(...) // params for boom core 2 + val boomTile3 = BoomTileParams(...) // params for boom core 3 + boomTile0 ++ boomTile1 ++ boomTile2 ++ boomTile3 + } + + case RocketTilesKey => { + val rocketTile0 = RocketTileParams(...) // params for rocket core 0 + val rocketTile1 = RocketTileParams(...) // params for rocket core 1 + rocketTile0 ++ rocketTile1 + } + }) + +Then you could use this new mixin like the following. + +.. code-block:: scala + + class SixCoreConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new WithHeterCoresSetup ++ + new freechips.rocketchip.system.BaseConfig) + +Note, in this setup you most likely dont need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the params yourself. + +Adding Hwachas +------------------------------------------- + +Adding a Hwacha accelerator is as easy as adding the ``DefaultHwachaConfig`` so that it can setup the Hwacha parameters and add itself to the ``BuildRoCC`` parameter. +An example of adding a Hwacha to all tiles in the system is below. + +.. code-block:: scala + + class DualCoreBoomAndRocketWithHwachasConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new hwacha.DefaultHwachaConfig ++ + new boom.system.WithRenumberHarts ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +In this example, Hwachas are added to both BOOM's and to the Rocket tile. +All with the same Hwacha parameters. + +Assigning Accelerators to Specific Tiles with MultiRoCC +------------------------------------------------------- + +Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a Mixin that provides support for adding RoCC accelerators to specific tiles in your SoC. +Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on the ``hartId`` of the tile. +For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles. +An example is shown below with two BOOM cores, and one Rocket attached to a Hwacha. + +.. code-block:: scala + + class DualCoreBoomAndOneHwachaRocketConfig extends Config( + new WithNormalBoomRocketTop ++ + new WithBootROM ++ + new WithMultiRoCC ++ + new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket + new boom.system.WithRenumberHarts ++ + new hwacha.DefaultHwachaConfig ++ + new boom.common.WithRVC ++ + new boom.common.DefaultBoomConfig ++ + new boom.system.WithNBoomCores(2) ++ + new freechips.rocketchip.subsystem.WithoutTLMonitors ++ + new freechips.rocketchip.subsystem.WithNBigCores(1) ++ + new freechips.rocketchip.system.BaseConfig) + +In this example, the ``WithRenumberHarts`` relabels the ``hartId``'s of all the BOOM/Rocket cores. +Then after that is applied to the parameters, the ``WithMultiRoCCHwacha(0)`` is used to assign to ``hartId`` zero a Hwacha (in this case ``hartId`` zero is Rocket). +Finally, the ``WithMultiRoCC`` mixin is called. +This mixin sets the ``BuildRoCC`` key to use the ``MultiRoCCKey`` instead of the default. +This must be used after all the RoCC parameters are set because it needs to override the ``BuildRoCC`` parameter. +If this is used earlier in the configuration sequence, then MultiRoCC does not work. + +This mixin can be changed to put more accelerators on more cores by changing the arguments to cover more ``hartId``'s (i.e. ``WithMultiRoCCHwacha(0,1,3,6,...)``). diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst new file mode 100644 index 00000000..6aa2a195 --- /dev/null +++ b/docs/Advanced-Usage/index.rst @@ -0,0 +1,11 @@ +Advanced Usage +================================ + +The following sections are advanced topics about how to use REBAR 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/index.rst b/docs/index.rst index ce083f2c..019a6991 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -37,6 +37,10 @@ New to Chipyard? Jump to the :ref:`Getting Started` page for more info. :numbered: VLSI/index + :maxdepth: 3 + :caption: Advanced Usage: + :numbered: + Advanced-Usage/index Indices and tables ================== From c61713d807c07d6435210e6a636f2a1cd9851c39 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Fri, 21 Jun 2019 11:52:00 -0700 Subject: [PATCH 12/15] removed extra core in names | misc cleanup --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 24 +++++++++---------- docs/Advanced-Usage/index.rst | 2 +- .../example/src/main/scala/Configs.scala | 6 ++--- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 2ee9cba4..596ba59b 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -1,7 +1,7 @@ Heterogeneous SoCs =============================== -The REBAR framework involves multiple cores and accelerators that can be composed in arbitrary ways. +The Chipyard framework involves multiple cores and accelerators that can be composed in arbitrary ways. This discussion will focus on how you combine Rocket, BOOM and Hwacha in particular ways to create a unique SoC. Creating a Rocket and BOOM System @@ -10,11 +10,11 @@ Creating a Rocket and BOOM System Instantiating an SoC with Rocket and BOOM cores is all done with the configuration system and two specific mixins. Both BOOM and Rocket have mixins labelled ``WithNBoomCores(X)`` and ``WithNBigCores(X)`` that automatically create ``X`` copies of the core. When used together you can create a heterogeneous system. -The following example shows a dual core BOOM with a single Rocket. +The following example shows a dual core BOOM with a single core Rocket. .. code-block:: scala - class DualCoreBoomAndRocketConfig extends Config( + class DualBoomAndOneRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new boom.system.WithRenumberHarts ++ @@ -33,8 +33,8 @@ This mixin applies to all the BOOM cores in the system and sets up the parameter Great! Now you have a heterogeneous setup with BOOMs and Rockets. The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId``. This is done with ``WithRenumberHarts`` (which can label the Rocket cores first or the BOOM cores first). -The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only that type of core in the system. -Thus, without the renumber mixin, each set of cores is labeled starting from zero. +The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only BOOM or only Rocket cores in the system. +Thus, without the ``WithRenumberHarts`` mixin, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``. Another option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core. The mixin to add to your system would look something like the following. @@ -68,7 +68,7 @@ Then you could use this new mixin like the following. new WithHeterCoresSetup ++ new freechips.rocketchip.system.BaseConfig) -Note, in this setup you most likely dont need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the params yourself. +Note, in this setup you most likely don't need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the tile parameters yourself. Adding Hwachas ------------------------------------------- @@ -78,7 +78,7 @@ An example of adding a Hwacha to all tiles in the system is below. .. code-block:: scala - class DualCoreBoomAndRocketWithHwachasConfig extends Config( + class DualBoomAndRocketWithHwachasConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new hwacha.DefaultHwachaConfig ++ @@ -90,25 +90,25 @@ An example of adding a Hwacha to all tiles in the system is below. new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -In this example, Hwachas are added to both BOOM's and to the Rocket tile. +In this example, Hwachas are added to both BOOM tiles and to the Rocket tile. All with the same Hwacha parameters. Assigning Accelerators to Specific Tiles with MultiRoCC ------------------------------------------------------- -Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a Mixin that provides support for adding RoCC accelerators to specific tiles in your SoC. +Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a mixin that provides support for adding RoCC accelerators to specific tiles in your SoC. Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on the ``hartId`` of the tile. For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles. -An example is shown below with two BOOM cores, and one Rocket attached to a Hwacha. +An example is shown below with two BOOM cores, and one Rocket tile with a Hwacha attached. .. code-block:: scala - class DualCoreBoomAndOneHwachaRocketConfig extends Config( + class DualBoomAndOneHwachaRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new WithMultiRoCC ++ new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket - new boom.system.WithRenumberHarts ++ + new boom.system.WithRenumberHarts(rocketFirst = true) ++ new hwacha.DefaultHwachaConfig ++ new boom.common.WithRVC ++ new boom.common.DefaultBoomConfig ++ diff --git a/docs/Advanced-Usage/index.rst b/docs/Advanced-Usage/index.rst index 6aa2a195..62dd11aa 100644 --- a/docs/Advanced-Usage/index.rst +++ b/docs/Advanced-Usage/index.rst @@ -1,7 +1,7 @@ Advanced Usage ================================ -The following sections are advanced topics about how to use REBAR and special features of the framework. +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:: diff --git a/generators/example/src/main/scala/Configs.scala b/generators/example/src/main/scala/Configs.scala index d6ff3432..4b5352d3 100644 --- a/generators/example/src/main/scala/Configs.scala +++ b/generators/example/src/main/scala/Configs.scala @@ -205,7 +205,7 @@ class GPIOBoomAndRocketConfig extends Config( new WithGPIOBoomRocketTop ++ new BaseBoomAndRocketConfig) -class DualCoreBoomAndOneRocketConfig extends Config( +class DualBoomAndOneRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new boom.system.WithRenumberHarts ++ @@ -216,12 +216,12 @@ class DualCoreBoomAndOneRocketConfig extends Config( new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -class DualCoreBoomAndOneHwachaRocketConfig extends Config( +class DualBoomAndOneHwachaRocketConfig extends Config( new WithNormalBoomRocketTop ++ new WithBootROM ++ new WithMultiRoCC ++ new WithMultiRoCCHwacha(0) ++ // put Hwacha just on hart0 which was renumbered to Rocket - new boom.system.WithRenumberHarts ++ + new boom.system.WithRenumberHarts(rocketFirst = true) ++ new hwacha.DefaultHwachaConfig ++ new boom.common.WithRVC ++ new boom.common.DefaultBoomConfig ++ From b3eeb70045ce08f4d5582cc1feeb5cfcb0cff0bf Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Sun, 23 Jun 2019 22:58:34 -0700 Subject: [PATCH 13/15] clarifications --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 596ba59b..1ac91633 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -25,13 +25,12 @@ The following example shows a dual core BOOM with a single core Rocket. new freechips.rocketchip.subsystem.WithNBigCores(1) ++ new freechips.rocketchip.system.BaseConfig) -In this example, the ``WithN...Cores(X)`` mixins set up particular parameters for the duplicated core. -For example, the Rocket tiles will be "BigCores" while BOOM has some generic parameters set in its mixin. -In BOOMs case, we override these base core parameters to create multiple "DefaultBoom"s with calling ``DefaultBoomConfig`` after the multi-core instantiation. -This mixin applies to all the BOOM cores in the system and sets up the parameters for each. +In this example, the ``WithNBoomCores`` and ``WithNBigCores`` mixins set up the default parameters for the multiple BOOM and Rocket cores, respectively. +However, for BOOM, an extra mixin called ``DefaultBoomConfig`` is added to override the default parameters with a "normal" sized out-of-order core. +This mixin applies to all BOOM cores in the system and changes the parameters for each. Great! Now you have a heterogeneous setup with BOOMs and Rockets. -The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId``. +The final thing you need to make this system work is to renumber the ``hartId``'s of the cores so that each core has a unique ``hartId`` (a ``hartId`` is the hardware thread id of the core). This is done with ``WithRenumberHarts`` (which can label the Rocket cores first or the BOOM cores first). The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only BOOM or only Rocket cores in the system. Thus, without the ``WithRenumberHarts`` mixin, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``. @@ -68,7 +67,7 @@ Then you could use this new mixin like the following. new WithHeterCoresSetup ++ new freechips.rocketchip.system.BaseConfig) -Note, in this setup you most likely don't need the ``WithRenumberHarts`` mixin since you have to assign the ``hartId`` of each tile in the tile parameters yourself. +Note, in this setup you need to specify the ``hartId`` of each core in the "TileParams", where each ``hartId`` is unique. Adding Hwachas ------------------------------------------- From 9fc0b9393cd040a0a2a7c8fb65fa32850c56a3ef Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Mon, 24 Jun 2019 14:32:49 -0700 Subject: [PATCH 14/15] more clarity on defaults --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 1ac91633..4afb6f20 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -26,7 +26,7 @@ The following example shows a dual core BOOM with a single core Rocket. new freechips.rocketchip.system.BaseConfig) In this example, the ``WithNBoomCores`` and ``WithNBigCores`` mixins set up the default parameters for the multiple BOOM and Rocket cores, respectively. -However, for BOOM, an extra mixin called ``DefaultBoomConfig`` is added to override the default parameters with a "normal" sized out-of-order core. +However, for BOOM, an extra mixin called ``DefaultBoomConfig`` is added to override the default parameters with a different set of more common default parameters. This mixin applies to all BOOM cores in the system and changes the parameters for each. Great! Now you have a heterogeneous setup with BOOMs and Rockets. From 44b1412c5e840330c92d1a98e5f98c87c3070465 Mon Sep 17 00:00:00 2001 From: abejgonzalez Date: Tue, 25 Jun 2019 09:22:06 -0700 Subject: [PATCH 15/15] clarify hwacha=rocc | alternative clarification --- docs/Advanced-Usage/Heterogeneous-SoCs.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Advanced-Usage/Heterogeneous-SoCs.rst b/docs/Advanced-Usage/Heterogeneous-SoCs.rst index 4afb6f20..96a7e40e 100644 --- a/docs/Advanced-Usage/Heterogeneous-SoCs.rst +++ b/docs/Advanced-Usage/Heterogeneous-SoCs.rst @@ -35,7 +35,7 @@ This is done with ``WithRenumberHarts`` (which can label the Rocket cores first The reason this is needed is because by default the ``WithN...Cores(X)`` mixin assumes that there are only BOOM or only Rocket cores in the system. Thus, without the ``WithRenumberHarts`` mixin, each set of cores is labeled starting from zero causing multiple cores to be assigned the same ``hartId``. -Another option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core. +Another alternative option to create a multi heterogeneous core system is to override the parameters yourself so you can specify the core parameters per core. The mixin to add to your system would look something like the following. .. code-block:: scala @@ -98,7 +98,7 @@ Assigning Accelerators to Specific Tiles with MultiRoCC Located in ``generators/example/src/main/scala/ConfigMixins.scala`` is a mixin that provides support for adding RoCC accelerators to specific tiles in your SoC. Named ``MultiRoCCKey``, this key allows you to attach RoCC accelerators based on the ``hartId`` of the tile. For example, using this allows you to create a 8 tile system with a RoCC accelerator on only a subset of the tiles. -An example is shown below with two BOOM cores, and one Rocket tile with a Hwacha attached. +An example is shown below with two BOOM cores, and one Rocket tile with a RoCC accelerator (Hwacha) attached. .. code-block:: scala