Skip to main content

Chisel Project Versioning

Chisel follows Semantic Versioning 2.0.0. Project versions are of the form MAJOR.MINOR.PATCH. An incremented MAJOR version means there may be backwards incompatible changes (typically after an appropriate deprecation schedule). An incremented MINOR version means there are changes in functionality (new APIs) in a backwards compatible manner. Importantly, Chisel maintains binary compatibility between minor versions of the same major version. For example, a project compiled against Chisel 5.0.0 can be used with future Chisel versions 5.1.0 or 5.100.2. An incremented PATCH version means there are backwards compatible bug fixes.

Firtool Version​

Starting with Chisel v3.6, Chisel uses firtool (part of the LLVM CIRCT project) to generate Verilog. Each version of Chisel is released against a specific version of firtool, shown in the tables below. Chisel automatically uses the corresponding version.

Setting Your Own Firtool Version​

tip

The following instructions apply when emitting SystemVerilog from Chisel APIs like ChiselStage. Users are also encouraged to emit .fir from Chisel and invoke an installed firtool binary separately using their build tool of choice.

To use a specific version, add a dependency on the desired org.chipsalliance::llvm-firtool release to your build. For example:

build.sbt
libraryDependencies += "org.chipsalliance" %% "llvm-firtool" % "1.153.0"
build.mill
def mvnDeps = Agg(
  mvn"org.chipsalliance::llvm-firtool:1.153.0"
)

Alternatively, you can install firtool yourself from the pre-built artifacts or build it from source. To use your own installed firtool binary, set CHISEL_FIRTOOL_PATH to the directory containing the firtool binary you want Chisel to use.

warning

A given version of Chisel is only tested against the version listed in the tables below. It often works with other versions, but it is not guaranteed.

Firtool Version Tables​

Chisel 7.x
Chisel VersionFirtool Version
7.14.01.155.0
7.13.01.149.0
7.12.01.146.0
7.11.01.144.0
7.10.01.143.0
7.9.01.140.0
7.8.01.139.0
7.7.01.139.0
7.6.01.138.0
7.5.01.138.0
7.4.01.137.0
7.3.01.135.0
7.2.01.133.0
7.1.11.131.0
7.1.01.131.0
7.0.01.128.0
Chisel 6.x
Chisel VersionFirtool Version
6.7.01.62.1
6.6.01.62.1
6.5.01.62.0
6.4.01.62.0
6.3.01.62.0
6.2.01.62.0
6.1.01.62.0
6.0.01.62.0
Chisel 5.x
Chisel VersionFirtool Version
5.3.01.43.0
5.2.01.43.0
5.1.01.43.0
5.0.01.40.0
Chisel 3.x
Chisel VersionFirtool Version
3.6.11.37.0
3.6.01.37.0

Old Chisel versions (3.0 - 3.6)​

As of Chisel 5.0.0, this and following sections no longer apply.

Prior to the release of Chisel 5.0.0, Chisel and related projects followed a versioning scheme similar to PVP. Project versions were of the form A.B.C where A.B specifies the Major version and C specifies the Minor version. Projects maintain binary compatibility between minor versions of the same major version.

Compatible Versions (Chisel 3.0 - 3.6)​

Historically, various Chisel-related projects were distributed across multiple projects each with their own versioning.

Please use the following table to determine which versions of the related projects are compatible. In particular, versions of projects in this table were compiled against the version of any dependencies listed in the same row. For example, chisel-iotesters version 1.4 was compiled against chisel3 version 3.3.

chisel3chiseltestchisel-iotesters3firrtltreadlediagrammerfirrtl-interpreter2
3.60.6-1.61.61.6-
3.50.542.551.51.541.54-
3.40.31.51.41.31.31.4
3.30.21.41.31.21.21.3
3.20.111.31.21.11.11.2
3.1-1.21.11.01.01.1
3.0-1.11.0--1.0

1 chiseltest 0.1 was published under artifact name chisel-testers2 (0.2 was published under both artifact names)
2 Replaced by Treadle, in maintenance mode only since version 1.1, final version is 1.4
3 Replaced by chiseltest, final version is 2.5
4 chiseltest, treadle, and diagrammer skipped X.4 to have a consistent major version with Chisel
5 chisel-iotesters skipped from 1.5 to 2.5 to have a consistent major version with Chisel