• Stars
    star
    3,570
  • Rank 11,746 (Top 0.3 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created almost 9 years ago
  • Updated 2 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Chisel: A Modern Hardware Design Language

Chisel

The Constructing Hardware in a Scala Embedded Language (Chisel) is an open-source hardware description language (HDL) used to describe digital electronics and circuits at the register-transfer level that facilitates advanced circuit generation and design reuse for both ASIC and FPGA digital logic designs.

Chisel adds hardware construction primitives to the Scala programming language, providing designers with the power of a modern programming language to write complex, parameterizable circuit generators that produce synthesizable Verilog. This generator methodology enables the creation of re-usable components and libraries, such as the FIFO queue and arbiters in the Chisel Standard Library, raising the level of abstraction in design while retaining fine-grained control.

For more information on the benefits of Chisel see: "What benefits does Chisel offer over classic Hardware Description Languages?"

Chisel is powered by FIRRTL (Flexible Intermediate Representation for RTL), a hardware compiler framework implemented by LLVM CIRCT.


Join the chat at https://gitter.im/freechipsproject/chisel3 Scaladoc CI GitHub tag (latest SemVer) Scala version support Scala version support (chisel3) Sonatype Snapshots

What does Chisel code look like?

LED blink

import chisel3._
import chisel3.util.Counter
import circt.stage.ChiselStage

class Blinky(freq: Int, startOn: Boolean = false) extends Module {
  val io = IO(new Bundle {
    val led0 = Output(Bool())
  })
  // Blink LED every second using Chisel built-in util.Counter
  val led = RegInit(startOn.B)
  val (_, counterWrap) = Counter(true.B, freq / 2)
  when(counterWrap) {
    led := ~led
  }
  io.led0 := led
}

object Main extends App {
  // These lines generate the Verilog output
  println(
    ChiselStage.emitSystemVerilog(
      new Blinky(1000),
      firtoolOpts = Array("-disable-all-randomization", "-strip-debug-info")
    )
  )
}

Should output the following Verilog:

Click to expand!

// Generated by CIRCT firtool-1.37.0
module Blinky(
  input  clock,
         reset,
  output io_led0
);

  reg       led;
  reg [8:0] counterWrap_c_value;
  always @(posedge clock) begin
    if (reset) begin
      led <= 1'h0;
      counterWrap_c_value <= 9'h0;
    end
    else begin
      automatic logic counterWrap = counterWrap_c_value == 9'h1F3;
      led <= counterWrap ^ led;
      if (counterWrap)
        counterWrap_c_value <= 9'h0;
      else
        counterWrap_c_value <= counterWrap_c_value + 9'h1;
    end
  end // always @(posedge)
  assign io_led0 = led;
endmodule

FIR Filter

Consider an FIR filter that implements a convolution operation, as depicted in this block diagram:

While Chisel provides similar base primitives as synthesizable Verilog, and could be used as such:

// 3-point moving sum implemented in the style of a FIR filter
class MovingSum3(bitWidth: Int) extends Module {
  val io = IO(new Bundle {
    val in = Input(UInt(bitWidth.W))
    val out = Output(UInt(bitWidth.W))
  })

  val z1 = RegNext(io.in)
  val z2 = RegNext(z1)

  io.out := (io.in * 1.U) + (z1 * 1.U) + (z2 * 1.U)
}

the power of Chisel comes from the ability to create generators, such as an FIR filter that is defined by the list of coefficients:

// Generalized FIR filter parameterized by the convolution coefficients
class FirFilter(bitWidth: Int, coeffs: Seq[UInt]) extends Module {
  val io = IO(new Bundle {
    val in = Input(UInt(bitWidth.W))
    val out = Output(UInt(bitWidth.W))
  })
  // Create the serial-in, parallel-out shift register
  val zs = Reg(Vec(coeffs.length, UInt(bitWidth.W)))
  zs(0) := io.in
  for (i <- 1 until coeffs.length) {
    zs(i) := zs(i-1)
  }

  // Do the multiplies
  val products = VecInit.tabulate(coeffs.length)(i => zs(i) * coeffs(i))

  // Sum up the products
  io.out := products.reduce(_ + _)
}

and use and re-use them across designs:

val movingSum3Filter = Module(new FirFilter(8, Seq(1.U, 1.U, 1.U)))  // same 3-point moving sum filter as before
val delayFilter = Module(new FirFilter(8, Seq(0.U, 1.U)))  // 1-cycle delay as a FIR filter
val triangleFilter = Module(new FirFilter(8, Seq(1.U, 2.U, 3.U, 2.U, 1.U)))  // 5-point FIR filter with a triangle impulse response

The above can be converted to Verilog using ChiselStage:

import chisel3.stage.ChiselGeneratorAnnotation
import circt.stage.{ChiselStage, FirtoolOption}

(new ChiselStage).execute(
  Array("--target", "systemverilog"),
  Seq(ChiselGeneratorAnnotation(() => new FirFilter(8, Seq(1.U, 1.U, 1.U))),
    FirtoolOption("--disable-all-randomization"))
)

Alternatively, you may generate some Verilog directly for inspection:

val verilogString = chisel3.getVerilogString(new FirFilter(8, Seq(0.U, 1.U)))
println(verilogString)

Getting Started

Bootcamp Interactive Tutorial

The online Chisel Bootcamp is the recommended way to get started with and learn Chisel. No setup is required (it runs in the browser), nor does it assume any prior knowledge of Scala.

The classic Chisel tutorial contains small exercises and runs on your computer.

A Textbook on Chisel

If you like a textbook to learn Chisel and also a bit of digital design in general, you may be interested in reading Digital Design with Chisel. It is available in English, Chinese, Japanese, and Vietnamese.

Build Your Own Chisel Projects

See the setup instructions for how to set up your environment to build Chisel locally.

When you're ready to build your own circuits in Chisel, we recommend starting from the Chisel Template repository, which provides a pre-configured project, example design, and testbench. Follow the chisel-template README to get started.

If you insist on setting up your own project from scratch, your project needs to depend on both the chisel-plugin (Scalac plugin) and the chisel library. For example, in SBT this could be expressed as:

// build.sbt
scalaVersion := "2.13.10"
val chiselVersion = "5.0.0"
addCompilerPlugin("org.chipsalliance" % "chisel-plugin" % chiselVersion cross CrossVersion.full)
libraryDependencies += "org.chipsalliance" %% "chisel" % chiselVersion

For Chisel prior to v5.0.0, Chisel was published using a different artifact name:

// build.sbt
scalaVersion := "2.13.10"
addCompilerPlugin("edu.berkeley.cs" % "chisel3-plugin" % "3.6.0" cross CrossVersion.full)
libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.6.0"
// We also recommend using chiseltest for writing unit tests
libraryDependencies += "edu.berkeley.cs" %% "chiseltest" % "0.6.0" % "test"

Guide For New Contributors

If you are trying to make a contribution to this project, please read CONTRIBUTING.md

Design Verification

These simulation-based verification tools are available for Chisel:

  • svsim is the lightweight testing library for Chisel, included in this repository.
  • chiseltest (Chisel 5.0 and before) is the batteries-included testing and formal verification library for Chisel-based RTL designs and a replacement for the former PeekPokeTester, providing the same base constructs but with a streamlined interface and concurrency support with fork and join with internal and Verilator integration for simulations.

Documentation

Useful Resources

If you are migrating from Chisel2, see the migration guide.

Chisel Dev Meeting

Chisel/FIRRTL development meetings happen every Monday from 9:00-10:00 am PT.

Call-in info and meeting notes are available here.

Data Types Overview

These are the base data types for defining circuit components:

Image

Contributor Documentation

This section describes how to get started contributing to Chisel itself, including how to test your version locally against other projects that pull in Chisel using sbt's managed dependencies.

Useful Resources for Contributors

The Useful Resources for users are also helpful for contributors.

Compiling and Testing Chisel

You must first install required dependencies to build Chisel locally, please see the setup instructions.

Clone and build the Chisel library:

git clone https://github.com/chipsalliance/chisel.git
cd chisel
sbt compile

In order to run the following unit tests, you will need several tools on your PATH, namely firtool, verilator, yosys, and espresso. Check that each is installed on your PATH by running which verilator and so on.

If the compilation succeeded and the dependencies noted above are installed, you can then run the included unit tests by invoking:

sbt test

Running Projects Against Local Chisel

To use the development version of Chisel (master branch), you will need to build from source and publish locally. The repository version can be found by running sbt version. As of the time of writing it was: 5.0.0-RC1+2-64bbd9ff-SNAPSHOT.

To publish your version of Chisel to the local Ivy (sbt's dependency manager) repository, run:

sbt "unipublish / publishLocal"

The compiled version gets placed in ~/.ivy2/local/org.chipsalliance/. If you need to un-publish your local copy of Chisel, remove the directory generated in ~/.ivy2/local/org.chipsalliance/.

In order to have your projects use this version of Chisel, you should update the libraryDependencies setting in your project's build.sbt file to use the current version, for example:

val chiselVersion = "5.0.0-RC1+2-64bbd9ff-SNAPSHOT"
addCompilerPlugin("org.chipsalliance" % "chisel-plugin" % chiselVersion cross CrossVersion.full)
libraryDependencies += "org.chipsalliance" %% "chisel" % chiselVersion

Chisel Architecture Overview

The Chisel compiler consists of these main parts:

  • The frontend, chisel3.*, which is the publicly visible "API" of Chisel and what is used in Chisel RTL. These just add data to the...
  • The Builder, chisel3.internal.Builder, which maintains global state (like the currently open Module) and contains commands, generating...
  • The intermediate data structures, chisel3.firrtl.*, which are syntactically very similar to Firrtl. Once the entire circuit has been elaborated, the top-level object (a Circuit) is then passed to...
  • The Firrtl emitter, chisel3.firrtl.Emitter, which turns the intermediate data structures into a string that can be written out into a Firrtl file for further processing.

Also included is:

  • The standard library of circuit generators, chisel3.util.*. These contain commonly used interfaces and constructors (like Decoupled, which wraps a signal with a ready-valid pair) as well as fully parameterizable circuit generators (like arbiters and multiplexors).
  • Chisel Stage, chisel3.stage.*, which contains compilation and test functions that are invoked in the standard Verilog generation and simulation testing infrastructure. These can also be used as part of custom flows.

Chisel Sub-Projects

Chisel consists of several Scala projects; each is its own separate compilation unit:

  • core is the bulk of the source code of Chisel, depends on firrtl, svsim, and macros
  • firrtl is the vestigial remains of the old Scala FIRRTL compiler, much if it will likely be absorbed into core
  • macros is most of the macros used in Chisel, no internal dependencies
  • plugin is the compiler plugin, no internal dependencies
  • src/main is the "main" that brings it all together and includes a util library, which depends on core
  • svsim is a low-level library for compiling and controlling SystemVerilog simulations, currently targeting Verilator and VCS as backends

Code that touches lots of APIs that are private to the chisel3 package should belong in core, while code that is pure Chisel should belong in src/main.

Which version should I use?

We encourage Chisel users (as opposed to Chisel developers), to use the latest release version of Chisel. This chisel-template repository is kept up-to-date, depending on the most recent version of Chisel. The recommended version is also captured near the top of this README, and in the Github releases section of this repo. If you encounter an issue with a released version of Chisel, please file an issue on GitHub mentioning the Chisel version and provide a simple test case (if possible). Try to reproduce the issue with the associated latest minor release (to verify that the issue hasn't been addressed).

For more information on our versioning policy and what versions of the various Chisel ecosystem projects work together, see Chisel Project Versioning.

If you're developing a Chisel library (or chisel3 itself), you'll probably want to work closer to the tip of the development trunk. By default, the main branch of the chisel repository is configured to build and publish its version of the code as <version>+<n>-<commit hash>-SNAPSHOT. Updated SNAPSHOTs are publised on every push to main. You are encouraged to do your development against the latest SNAPSHOT, but note that neither API nor ABI compatibility is guaranteed so your code may break at any time.

Roadmap

See Roadmap.

More Repositories

1

rocket-chip

Rocket Chip Generator
Scala
2,907
star
2

verible

Verible is a suite of SystemVerilog developer tools, including a parser, style-linter, formatter and language server
C++
1,152
star
3

riscv-dv

Random instruction generator for RISC-V processor verification
Python
928
star
4

Cores-VeeR-EH1

VeeR EH1 core
SystemVerilog
752
star
5

firrtl

Flexible Intermediate Representation for RTL
Scala
664
star
6

Surelog

SystemVerilog 2017 Pre-processor, Parser, Elaborator, UHDM Compiler. Provides IEEE Design/TB C/C++ VPI and Python AST & UHDM APIs. Compiles on Linux gcc, Windows msys2-gcc & msvc, OsX
C++
321
star
7

f4pga

FOSS Flow For FPGA
Python
297
star
8

sv-tests

Test suite designed to check compliance with the SystemVerilog standard.
SystemVerilog
255
star
9

f4pga-examples

Example designs showing different ways to use F4PGA toolchains.
Verilog
253
star
10

VeeRwolf

FuseSoC-based SoC for SweRV EH1 and EL2
Verilog
243
star
11

Cores-VeeR-EL2

VeeR EL2 Core
SystemVerilog
208
star
12

Cores-VeeR-EH2

SystemVerilog
200
star
13

dromajo

RISC-V RV64GC emulator designed for RTL co-simulation
C++
192
star
14

UHDM

Universal Hardware Data Model. A complete modeling of the IEEE SystemVerilog Object Model with VPI Interface, Elaborator, Serialization, Visitor and Listener. Used as a compiled interchange format in between SystemVerilog tools. Compiles on Linux gcc, Windows msys2-gcc & msvc, OsX
C++
178
star
15

treadle

Chisel/Firrtl execution engine
Scala
146
star
16

silicon-notebooks

Jupyter Notebook
137
star
17

synlig

SystemVerilog support for Yosys
Verilog
118
star
18

aib-phy-hardware

Advanced Interface Bus (AIB) die-to-die hardware open source
Verilog
116
star
19

fpga-tool-perf

FPGA tool performance profiling
Python
95
star
20

VeeR-ISS

C++
94
star
21

fasm

FPGA Assembly (FASM) Parser and Generator
Python
82
star
22

yosys-f4pga-plugins

Plugins for Yosys developed as part of the F4PGA project.
Verilog
81
star
23

t1

Scala
80
star
24

Caliptra

Caliptra IP and firmware for integrated Root of Trust block
80
star
25

playground

chipyard in mill :P
Scala
71
star
26

omnixtend

OmniXtend cache coherence protocol
TeX
70
star
27

uvm-verilator

SystemVerilog
50
star
28

rocket-tools

Software tools that support rocket-chip (GNU toolchain, ISA simulator, tests)
Shell
46
star
29

AIB-specification

Home of the Advanced Interface Bus (AIB) specification.
45
star
30

caliptra-rtl

HW Design Collateral for Caliptra RoT IP
SystemVerilog
45
star
31

fpga-interchange-schema

Cap'n Proto
44
star
32

cde

A Scala library for Context-Dependent Environments
Scala
39
star
33

python-fpga-interchange

Python interface to FPGA interchange format
Python
38
star
34

Cores-SweRV_fpga

Tcl
36
star
35

firrtl-spec

The specification for the FIRRTL language
TeX
32
star
36

caliptra-sw

Caliptra software (ROM, FMC, runtime firmware), and libraries/tools needed to build and test
Rust
31
star
37

UHDM-integration-tests

Verilog
29
star
38

espresso

C
28
star
39

f4pga-sdf-timing

Python library for working Standard Delay Format (SDF) Timing Annotation files.
Python
27
star
40

aib-phy-generator

AIB Generator: Analog hardware compiler for AIB PHY
Shell
26
star
41

verible-linter-action

Automatic SystemVerilog linting in github actions with the help of Verible
Python
21
star
42

riscv-fw-infrastructure

SDK Firmware infrastructure, contain RTOS Abstraction Layer, demos, SweRV Processor Support Package, and more ...
C
21
star
43

aib-protocols

SystemVerilog
20
star
44

systemc-compiler

Intel Compiler for SystemC
C++
16
star
45

tilelink

Scala
16
star
46

f4pga-xc7-bram-patch

Tool for updating the contents of BlockRAMs found in Xilinx 7 series bitstreams.
LLVM
15
star
47

Cores-SweRV-Support-Package

Processor support packages
Python
15
star
48

rocket

The working draft to split rocket core out from rocket chip
Scala
14
star
49

homebrew-verible

Ruby
14
star
50

tools-cocotb-verilator-build

Makefile
14
star
51

f4pga-bitstream-viewer

Tool for graphically viewing FPGA bitstream files and their connection to FASM features.
Python
13
star
52

caliptra-dpe

High level module that implements DPE and defines high-level traits that are used to communicate with the crypto peripherals and PCRs
Rust
13
star
53

rocket-chip-fpga-shells

Wrapper shells enabling designs generated by rocket-chip to map onto certain FPGA boards
Scala
13
star
54

ideas

13
star
55

diplomacy

Scala
12
star
56

rocket-chip-blocks

RTL blocks compatible with the Rocket Chip Generator
Scala
11
star
57

OmnixtendEndpoint

Hardware implementation of an OmniXtend Memory Endpoint/Lowest Point of Coherence.
Bluespec
10
star
58

foundation

Governance-related CHIPS Alliance documents, guides etc.
10
star
59

rocket-chip-inclusive-cache

An RTL generator for a last-level shared inclusive TileLink cache controller
Scala
9
star
60

f4pga-v2x

Tool for converting specialized annotated Verilog models into XML needed for Verilog to Routing flow.
Python
9
star
61

f4pga-xc-fasm2bels

Library to convert a FASM file into BELs importable into Vivado.
Verilog
8
star
62

fpga-interchange-tests

Repository to run extensive tests on the FPGA interchange format
Verilog
8
star
63

tree-sitter-firrtl

FIRRTL grammar for tree-sitter
C++
8
star
64

verible-formatter-action

SystemVerilog
6
star
65

f4pga-database-visualizer

JavaScript
6
star
66

tsc

CHIPS Alliance Technical Steering Committee
5
star
67

f4pga-xc-fasm

Python
5
star
68

sv-tests-results

Output of the sv-tests runs.
HTML
4
star
69

rocket-pcb

PCB libraries and templates for rocket-chip based FPGA/ASIC designs
Verilog
4
star
70

chips-alliance-website

SCSS
3
star
71

caliptra-ureg

3
star
72

f4pga-rr-graph

Collection of Routing Resources Graph (RR Graph) libraries for VPR
Python
2
star
73

riscv-v-spec

Working draft of the proposed RISC-V V vector extension
Assembly
2
star
74

vtr-xml-utils

XSLT
2
star
75

EasyCLA-code_only

1
star
76

EasyCLA-specs_and_code

1
star
77

artwork

CHIPS Alliance artwork
1
star
78

wg-analog

CHIPS Alliance Analog Working Group
1
star
79

caliptra-cfi

Code-flow Integrity module to mitigate glitches and fault injections
Rust
1
star
80

rocket-pcblib

1
star