Merge branch 'main' into klayout-docs

docs/Advanced-Concepts/CDEs.rst

@@ -21,24 +21,37 @@ Consider the following example using CDEs.
 
     class WithX(b: Boolean) extends Config((site, here, up) => {
       case SomeKeyX => b
-    }
+    })
 
     class WithY(b: Boolean) extends Config((site, here, up) => {
       case SomeKeyY => b
-    }
+    })
 
 
 When forming a query based on a ``Parameters`` object, like ``p(SomeKeyX)``, the configuration system traverses the "chain" of config fragments until it finds a partial function which is defined at the key, and then returns that value.
 
 .. code:: scala
 
-    val params = Config(new WithX(true) ++ new WithY(true)) // "chain" together config fragments
+    val params = new Config(new WithX(true) ++ new WithY(true)) // "chain" together config fragments
     params(SomeKeyX) // evaluates to true
     params(SomeKeyY) // evaluates to true
     params(SomeKeyZ) // evaluates to false
 
 In this example, the evaluation of ``params(SomeKeyX)`` will terminate in the partial function defined in ``WithX(true)``, while the evaluation of ``params(SomeKeyY)`` will terminate in the partial function defined in ``WithY(true)``. Note that when no partial functions match, the evaluation will return the default value for that parameter.
 
+Config fragments take precedence from left to right, meaning that a fragment at the start of the chain can override the value of a fragment to the right. It helps to read the fragment chain from right to left.
+
+.. code:: scala
+
+    case object SomeKeyX extends Field[Int](0)
+
+    class WithX(n: Int) extends Config((site, here, up) => {
+      case SomeKeyX => n
+    })
+
+    val params = new Config(new WithX(10) ++ new WithX(5))
+    println(params(SomeKeyX)) // evaluates to 10
+
 The real power of CDEs arises from the ``(site, here, up)`` parameters to the partial functions, which provide useful "views" into the global parameterization that the partial functions may access to determine a parameterization.
 
 .. note::
@@ -54,10 +67,10 @@ Site
 
     class WithXEqualsYSite extends Config((site, here, up) => {
       case SomeKeyX => site(SomeKeyY) // expands to site(SomeKeyY, site)
-    }
+    })
 
-    val params_1 = Config(new WithXEqualsYSite ++ new WithY(true))
-    val params_2 = Config(new WithY(true) ++ new WithXEqualsYSite)
+    val params_1 = new Config(new WithXEqualsYSite ++ new WithY(true))
+    val params_2 = new Config(new WithY(true) ++ new WithXEqualsYSite)
     params_1(SomeKeyX) // evaluates to true
     params_2(SomeKeyX) // evaluates to true
 
@@ -75,10 +88,10 @@ Here
     class WithXEqualsYHere extends Config((site, here, up) => {
       case SomeKeyY => false
       case SomeKeyX => here(SomeKeyY, site)
-    }
+    })
 
-    val params_1 = Config(new WithXEqualsYHere ++ new WithY(true))
-    val params_2 = Config(new WithY(true) ++ new WithXEqualsYHere)
+    val params_1 = new Config(new WithXEqualsYHere ++ new WithY(true))
+    val params_2 = new Config(new WithY(true) ++ new WithXEqualsYHere)
 
     params_1(SomeKeyX) // evaluates to false
     params_2(SomeKeyX) // evaluates to false
@@ -95,10 +108,10 @@ Up
 
     class WithXEqualsYUp extends Config((site, here, up) => {
       case SomeKeyX => up(SomeKeyY, site)
-    }
+    })
 
-    val params_1 = Config(new WithXEqualsYUp ++ new WithY(true))
-    val params_2 = Config(new WithY(true) ++ new WithXEqualsYUp)
+    val params_1 = new Config(new WithXEqualsYUp ++ new WithY(true))
+    val params_2 = new Config(new WithY(true) ++ new WithXEqualsYUp)
 
     params_1(SomeKeyX) // evaluates to true
     params_2(SomeKeyX) // evaluates to false

docs/Chipyard-Basics/Initial-Repo-Setup.rst

@@ -27,15 +27,8 @@ Conda allows users to create an "environment" that holds system dependencies lik
 
 .. Note:: Chipyard can also run on systems without a Conda installation. However, users on these systems must manually install toolchains and dependencies.
 
-First, Chipyard requires Conda to be installed on the system.
-Please refer to the `Conda installation instructions <https://github.com/conda-forge/miniforge/#download>`__ on how to install Conda with the **Miniforge** installer.
-Afterwards, verify that Conda is a sufficient version (we test on version 4.12.0 but higher is most likely fine).
-
-.. Note:: If you have installed conda separately from this documentation (i.e. from miniconda or full Anaconda), please ensure you follow https://conda-forge.org/docs/user/introduction.html#how-can-i-install-packages-from-conda-forge to use ``conda-forge`` packages without any issues.
-
-.. code-block:: shell
-
-    conda --version # must be version 22.11.1 or higher
+First, Chipyard requires the latest Conda to be installed on the system.
+Please refer to the `Conda installation instructions <https://github.com/conda-forge/miniforge/#download>`__ on how to install the latest Conda with the **Miniforge** installer.
 
 After Conda is installed and is on your ``PATH``, we need to install a version of ``git`` to initially checkout the repository.
 For this you can use the system package manager like ``yum`` or ``apt`` to install ``git``.
@@ -71,7 +64,27 @@ Run the following script based off which compiler you would like to use.
 .. Note:: Prior versions of Chipyard recommended ``esp-tools`` for Gemmini development. Gemmini should now be used with the standard ``riscv-tools``.
 
 .. Warning:: The following script will complete a "full" installation of Chipyard which may take a long time depending on the system.
-    Ensure that this script completes fully (no interruptions) before continuing on.
+    Ensure that this script completes fully (no interruptions) before continuing on. User can use the ``--skip`` or ``-s`` flag to skip steps:
+
+    ``-s 1`` skips initializing Conda environment
+
+    ``-s 2`` skips initializing Chipyard submodules
+
+    ``-s 3`` skips initializing toolchain collateral (Spike, PK, tests, libgloss)
+
+    ``-s 4`` skips initializing ctags
+
+    ``-s 5`` skips pre-compiling Chipyard Scala sources
+
+    ``-s 6`` skips initializing FireSim
+
+    ``-s 7`` skips pre-compiling FireSim sources
+
+    ``-s 8`` skips initializing FireMarshal
+
+    ``-s 9`` skips pre-compiling FireMarshal default buildroot Linux sources
+
+    ``-s 10`` skips running repository clean-up
 
 .. code-block:: shell
 
@@ -120,7 +133,7 @@ You can source this file in your ``.bashrc`` or equivalent environment setup fil
     However, it is recommended that the final ``env.sh`` file sourced is the ``env.sh`` located in the
     Chipyard repo that you expect to run ``make`` commands in.
 
-Pre-built Docker Image
+DEPRECATED: Pre-built Docker Image
 -------------------------------------------
 
 An alternative to setting up the Chipyard repository locally is to pull the pre-built Docker image from Docker Hub. The image comes with all dependencies installed, Chipyard cloned, and toolchains initialized. This image sets up baseline Chipyard (not including FireMarshal, FireSim, and Hammer initializations). Each image comes with a tag that corresponds to the version of Chipyard cloned/set-up in that image. Not including a tag during the pull will pull the image with the latest version of Chipyard.

docs/Customization/Custom-Chisel.rst

@@ -52,8 +52,22 @@ Then add ``yourproject`` to the Chipyard top-level build.sbt file.
 
 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
-the ``chipyard`` project, change the final line in build.sbt to the following.
+the ``chipyard`` project, add your project to the list of sub-projects in the 
+`.dependsOn()` for `lazy val chipyard`. The original code may change over time, but it
+should look something like this:
 
 .. code-block:: scala
 
-    lazy val chipyard = (project in file(".")).settings(commonSettings).dependsOn(testchipip, yourproject)
+    lazy val chipyard = (project in file("generators/chipyard"))
+        .dependsOn(testchipip, rocketchip, boom, hwacha, sifive_blocks, sifive_cache, iocell,
+            sha3, dsptools, `rocket-dsp-utils`,
+            gemmini, icenet, tracegen, cva6, nvdla, sodor, ibex, fft_generator,
+            yourproject, // <- added to the middle of the list for simplicity
+            constellation, mempress)
+        .settings(libraryDependencies ++= rocketLibDeps.value)
+        .settings(
+            libraryDependencies ++= Seq(
+            "org.reflections" % "reflections" % "0.10.2"
+            )
+        )
+        .settings(commonSettings)

docs/Customization/Memory-Hierarchy.rst

@@ -94,7 +94,7 @@ memory channel.
 
 Instead of connecting to off-chip DRAM, you can instead connect a scratchpad
 and remove the off-chip link. This is done by adding a fragment like
-``testchipip.WithBackingScratchpad`` to your configuration and removing the
+``testchipip.WithScratchpad`` to your configuration and removing the
 memory port with ``freechips.rocketchip.subsystem.WithNoMemPort``.
 
 .. literalinclude:: ../../generators/chipyard/src/main/scala/config/RocketConfigs.scala

docs/VLSI/ASAP7-Tutorial.rst

@@ -66,6 +66,12 @@ In the Chipyard root, ensure that you have the Chipyard conda environment activa
 
 to pull and install the plugin submodules. Note that for technologies other than ``sky130`` or ``asap7``, the tech submodule must be added in the ``vlsi`` folder first.
 
+Now navigate to the ``vlsi`` directory. The remainder of the tutorial will assume you are in this directory.
+
+.. code-block:: shell
+
+    cd ~chipyard/vlsi
+
 Building the Design
 --------------------
 To elaborate the ``TinyRocketConfig`` and set up all prerequisites for the build system to push the design and SRAM macros through the flow: