Skip to content

Latest commit

 

History

History
140 lines (88 loc) · 6.83 KB

CONTRIBUTING.md

File metadata and controls

140 lines (88 loc) · 6.83 KB
Raw

GUIDE TO CONTRIBUTING

  1. If you need help on making a pull request, follow this guide.

  2. To understand how to compile and test chisel3 from the source code, install the required dependencies.

  3. In order to contribute to chisel3, you'll need to sign the CLA agreement. You will be asked to sign it upon your first pull request.

  1. To introduce yourself and get help, you can join the gitter forum. If you have any questions or concerns, you can get help there.

  2. You can peruse the good-first-issues for easy tasks to start with. Another easy thing to start with is doing your own pass of the website looking for typos, pages missing their titles, etc. The sources for the website are here.

  3. Please make your PRs against the main branch. The project admins, when reviewing your PR, will decide which stable version (if any) your change should be backported to. They will apply the appropriate milestone marker which controls which branches the backport will be opened to. The backports will be opened automatically on your behalf once your main PR is merged.

  4. The PR template will require you to select "Type of Improvement." A reviewer or someone with write access will add the appropriate label to your PR based on this type of improvement which will include your PR in the correct category in the release notes.

  5. If your backport PR(s) get labeled with bp-conflict, it means they cannot be automatically be merged. You can help get them merged by openening a PR against the already-existing backport branch (will be named something like mergify/bp/3.5.x/pr-2512) with the necessary cleanup changes. The admins will merge your cleanup PR and remove the bp-conflict label if appropriate.

Building and Testing

Dependencies

Chisel uses the Mill build tool. You can install it as described on the Chisel installation instructions, or just use the bootstrap script in this repository: ./mill. Developers should read the Mill documentation to understand the basic commands and use.

The main dependencies for development are the JDK and git. Any JDK 8 or newer will work for most development, but note that developing the CIRCT Panama bindings requires Java 21. Coursier's command-line is useful for hot swapping JDKs. For example:

eval $(cs java --jvm graalvm-java21 --env)

This will swap the JDK in your shell to the latest release of GraalVM Java 21.

Useful commands

Mill's resolve command plus the wildcard _ are useful for discovering available projects, tasks, and commands.

# See all projects
./mill resolve _

# See all cross-compile versions for the 'chisel' build unit
./mill resolve chisel._

# See all available tasks and commands for all 'chisel' build unit
./mill resolve chisel.__

You can compile everything with (note this includes the CIRCT Panama bindings so requires Java 21):

./mill __.compile

Most testing can be done on just the Chisel build unit:

./mill chisel[2.13.15].test.test

You can test everything with:

./mill __.test

Note the cross-version will likely change in the future, use ./mill resolve chisel._ to see latest version.

Chisel uses ScalaTest so you can run individual tests using standard ScalaTest commands and arguments, e.g.

./mill chisel[2.13.15].test.testOnly chiselTests.VecLiteralSpec -- -z "lits must fit in vec element width"

Formatting

Chisel enforces formatting using Scalafmt. To format the code, run:

# Reformat normal source files
./mill __.reformat

# Reformat mill build files
./mill --meta-level 1 mill.scalalib.scalafmt.ScalafmtModule/reformatAll sources

Internal Documentation

This section describes the internal Chisel components for contributors.

CIRCT Converter

There is a highly experimental component CIRCT Converter (a.k.a. Panama Converter). It is powered by Java's Panama framework to interact directly with CIRCT by calling the C-APIs of MLIR and CIRCT directly from Scala, enabling seamless emitting Chisel IR to CIRCT FIRRTL Dialect IR (no serialization and deserialization for FIRRTL), flexible executing Passes with PassManager, lowering to / exporting SystemVerilog, accesing OM data, and more.

Directory circtpanamabinding

Here defines the needed CIRCT items that will be processed by the Panama framework's jextract tool for codegen FFI Java code to use in Scala.

When you need to use new APIs, add their names to the corresponding files according to the category, then recompile, and the mill build system will automatically process these files, invoking jextract to generate Java FFI code for you.

The Panama framework requires exact Java 21, and requires extra javac options to link libraries --enable-native-access=ALL-UNNAMED --enable-preview -Djava.library.path=<lib-path>. See examples from lit tests, e.g. SmokeTest.sc.

Directory panamalib

It provides a type-safe wrapper for the FFI code generated by jextract.

File PanamaCIRCTConverter.scala

Here is the implementation of how each Chisel IR will be emitted to the CIRCT.

It needs to be highly synchronized with CIRCT upstream. When updating it, you can refer to CIRCT's FIRRTL Dialect documentation. Some dialect-specific types, conversions may require a specialized C-API function to return from CIRCT, in which case you can open a PR in CIRCT upstream to add it and use it here.

File PanamaCIRCTPassManager.scala

It provides a PassManager, which is used in place of the firtool cli.

File PanamaCIRCTOM.scala

After using PassManager to lowering the FIRRTL Dialect to the HW Dialect, you will be able to access the OM data in it.

The data types of the OM are defined here, as well as the way to access them. This is an example of printing out all the Top_Class fields.

val pm = converter.passManager()
assert(pm.populateFinalizeIR())
assert(pm.run())

val om = converter.om()
val evaluator = om.evaluator()

val top = evaluator.instantiate("Top_Class", Seq(om.newBasePathEmpty)).get
top.foreachField((name, value) => println(s".$name => { ${value.toString} }"))