Rocket Chip Documentation

To complete a Diplomacy graph, you must bind nodes together in a top-level module (often a LazyModule acting as a testbench). The most common binding operator is :=.

• Directionality: Sinks are typically placed on the left-hand side, and sources on the right-hand side (e.g., sinkNode := sourceNode).
• Binding multiple nodes: You can iterate through sequences of nodes to establish multiple connections between modules.

Rocket Chip uses mill as its build tool and nix to configure the development environment. Follow these steps to enable language server support in your IDE.

1. Install nix for your OS.
2. Generate the BSP configuration:

   mill mill.bsp.BSP/install

3. Patch the .bsp/mill-bsp.json file. Change the argv array to use nix develop so the IDE runs Mill within the Nix environment.

For IntelliJ:

• Install the Scala plugin.
• If BSP doesn't run automatically, click bsp in the right sidebar and right-click your project to reload.

For VSCode:

• Install the Metals extension.
• Run the command Metals: Import build.

To keep your local repository up-to-date with the upstream master branch, pull the latest changes and recursively update the submodules.

If the rocket-tools version has changed, you must recompile and install it by running the build scripts within the rocket-tools directory.

The documentation in this repository is partially generated from source files using mdoc. To generate the documentation, ensure you are in the repository's root directory and run the docs/mdoc command from SBT.

The resulting documentation will be output to the generated folder.

Because Diplomacy performs parameter negotiation lazily after the graph is constructed, hardware must be defined using the LazyModule pattern:

1. Extend LazyModule to define the module structure and its Diplomacy nodes.
2. Define the actual Chisel hardware inside a lazy val module = new LazyModuleImp(this) { ... } block.
3. Inside LazyModuleImp, you can access negotiated parameters via the nodes (e.g., node.in or node.out) to parameterize Chisel wires, bundles, and logic.

class Adder(implicit p: Parameters) extends LazyModule {
  val node = new AdderNode(...) // Define node here

  lazy val module = new LazyModuleImp(this) {
    require(node.in.size >= 2)
    node.out.head._1 := node.in.unzip._1.reduce(_ + _)
  }

  override lazy val desiredName = "Adder"
}

To use the Rocket Chip generator, clone the repository and initialize the required Git submodules.

Note: You must also install dependencies for rocket-tools (see its specific README) and chisel3 (see Chisel3 installation guides) to ensure a functional environment.

$ git clone https://github.com/ucb-bar/rocket-chip.git
$ cd rocket-chip
$ git submodule update --init

To add externally driven interrupts to a BaseSubsystem, use one of the following synchronization traits. Do not use HasExtInterrupts directly.

• HasAsyncExtInterrupts: Use this if the external interrupts have NOT yet been synchronized to the Periphery (PLIC) clock. It automatically wires extInterrupts to ibus.fromAsync.
• HasSyncExtInterrupts: Use this if the external interrupts have ALREADY been synchronized to the Periphery (PLIC) clock. It automatically wires extInterrupts to ibus.fromSync.

Rocket Chip uses GitHub Actions caching for riscv-tools and Verilator. While caches are automatically invalidated when riscv-tools.hash or verilator.hash changes, you can manually force an invalidation by incrementing the version number in the cache key within the workflow configuration.

To invalidate a cache:

1. Open .github/workflows/continuous-integration.yml.
2. Find the job (e.g., prepare-riscv-tools-cache) containing the actions/cache@* step.
3. Locate the key property. The key ends with a version suffix like -v1.
4. Increment this number (e.g., change -v1 to -v2).
5. Crucially, find all other occurrences of that specific cache key within the same file and increment them to match the new version number.
6. Commit and push the changes to trigger a new cache build.