Skip to main content

Polymorphism and Parameterization

This section is advanced and can be skipped at first reading.

Scala is a strongly typed language and uses parameterized types to specify generic functions and classes. In this section, we show how Chisel users can define their own reusable functions and classes using parameterized classes.

Parameterized Functions​

Earlier we defined Mux2 on Bool, but now we show how we can define a generic multiplexer function. We define this function as taking a boolean condition and con and alt arguments (corresponding to then and else expressions) of type T:

def Mux[T <: Bits](c: Bool, con: T, alt: T): T = { ... }

where T is required to be a subclass of Bits. Scala ensures that in each usage of Mux, it can find a common superclass of the actual con and alt argument types, otherwise it causes a Scala compilation type error. For example,

Mux(c, UInt(10), UInt(11))

yields a UInt wire because the con and alt arguments are each of type UInt.

Parameterized Classes​

Like parameterized functions, we can also parameterize classes to make them more reusable. For instance, we can generalize the Filter class to use any kind of link. We do so by parameterizing the FilterIO class and defining the constructor to take a single argument gen of type T as below.

class FilterIO[T <: Data](gen: T) extends Bundle {
  val x = Input(gen)
  val y = Output(gen)
}

We can now define Filter by defining a module class that also takes a link type constructor argument and passes it through to the FilterIO interface constructor:

class Filter[T <: Data](gen: T) extends Module {
  val io = IO(new FilterIO(gen))
  // ...
}

We can now define a PLink-based Filter as follows:

val f = Module(new Filter(new PLink))

A generic FIFO could be defined as follows:

import chisel3.util.log2Up

class DataBundle extends Bundle {
  val a = UInt(32.W)
  val b = UInt(32.W)
}

class Fifo[T <: Data](gen: T, n: Int) extends Module {
  val io = IO(new Bundle {
    val enqVal = Input(Bool())
    val enqRdy = Output(Bool())
    val deqVal = Output(Bool())
    val deqRdy = Input(Bool())
    val enqDat = Input(gen)
    val deqDat = Output(gen)
  })
  val enqPtr     = RegInit(0.U((log2Up(n)).W))
  val deqPtr     = RegInit(0.U((log2Up(n)).W))
  val isFull     = RegInit(false.B)
  val doEnq      = io.enqRdy && io.enqVal
  val doDeq      = io.deqRdy && io.deqVal
  val isEmpty    = !isFull && (enqPtr === deqPtr)
  val deqPtrInc  = deqPtr + 1.U
  val enqPtrInc  = enqPtr + 1.U
  val isFullNext = Mux(doEnq && ~doDeq && (enqPtrInc === deqPtr),
                         true.B, Mux(doDeq && isFull, false.B,
                         isFull))
  enqPtr := Mux(doEnq, enqPtrInc, enqPtr)
  deqPtr := Mux(doDeq, deqPtrInc, deqPtr)
  isFull := isFullNext
  val ram = Mem(n, gen)
  when (doEnq) {
    ram(enqPtr) := io.enqDat
  }
  io.enqRdy := !isFull
  io.deqVal := !isEmpty
  ram(deqPtr) <> io.deqDat
}

An Fifo with 8 elements of type DataBundle could then be instantiated as:

val fifo = Module(new Fifo(new DataBundle, 8))

It is also possible to define a generic decoupled (ready/valid) interface:

class DecoupledIO[T <: Data](data: T) extends Bundle {
  val ready = Input(Bool())
  val valid = Output(Bool())
  val bits  = Output(data)
}

This template can then be used to add a handshaking protocol to any set of signals:

class DecoupledDemo extends DecoupledIO(new DataBundle)

The FIFO interface can be now be simplified as follows:

class Fifo[T <: Data](data: T, n: Int) extends Module {
  val io = IO(new Bundle {
    val enq = Flipped(new DecoupledIO(data))
    val deq = new DecoupledIO(data)
  })
  // ...
}

Parametrization based on Modules​

You can also parametrize modules based on other modules rather than just types. The following is an example of a module parametrized by other modules as opposed to e.g. types.

import chisel3.RawModule
import chisel3.experimental.BaseModule
import circt.stage.ChiselStage

// Provides a more specific interface since generic Module
// provides no compile-time information on generic module's IOs.
trait MyAdder {
    def in1: UInt
    def in2: UInt
    def out: UInt
}

class Mod1 extends RawModule with MyAdder {
    val in1 = IO(Input(UInt(8.W)))
    val in2 = IO(Input(UInt(8.W)))
    val out = IO(Output(UInt(8.W)))
    out := in1 + in2
}

class Mod2 extends RawModule with MyAdder {
    val in1 = IO(Input(UInt(8.W)))
    val in2 = IO(Input(UInt(8.W)))
    val out = IO(Output(UInt(8.W)))
    out := in1 - in2
}

class X[T <: BaseModule with MyAdder](genT: => T) extends Module {
    val io = IO(new Bundle {
        val in1 = Input(UInt(8.W))
        val in2 = Input(UInt(8.W))
        val out = Output(UInt(8.W))
    })
    val subMod = Module(genT)
    io.out := subMod.out
    subMod.in1 := io.in1
    subMod.in2 := io.in2
}

println(ChiselStage.emitSystemVerilog(new X(new Mod1)))
println(ChiselStage.emitSystemVerilog(new X(new Mod2)))

Output:

// Generated by CIRCT firtool-1.73.0
module Mod1(	// polymorphism-and-parameterization.md:170:7
  input  [7:0] in1,	// polymorphism-and-parameterization.md:171:17
               in2,	// polymorphism-and-parameterization.md:172:17
  output [7:0] out	// polymorphism-and-parameterization.md:173:17
);

  assign out = in1 + in2;	// polymorphism-and-parameterization.md:170:7, :174:16
endmodule

module X(	// polymorphism-and-parameterization.md:186:7
  input        clock,	// polymorphism-and-parameterization.md:186:7
               reset,	// polymorphism-and-parameterization.md:186:7
  input  [7:0] io_in1,	// polymorphism-and-parameterization.md:187:16
               io_in2,	// polymorphism-and-parameterization.md:187:16
  output [7:0] io_out	// polymorphism-and-parameterization.md:187:16
);

  Mod1 subMod (	// polymorphism-and-parameterization.md:192:24
    .in1 (io_in1),
    .in2 (io_in2),
    .out (io_out)
  );	// polymorphism-and-parameterization.md:192:24
endmodule

// Generated by CIRCT firtool-1.73.0
module Mod2(	// polymorphism-and-parameterization.md:178:7
  input  [7:0] in1,	// polymorphism-and-parameterization.md:179:17
               in2,	// polymorphism-and-parameterization.md:180:17
  output [7:0] out	// polymorphism-and-parameterization.md:181:17
);

  assign out = in1 - in2;	// polymorphism-and-parameterization.md:178:7, :182:16
endmodule

module X(	// polymorphism-and-parameterization.md:186:7
  input        clock,	// polymorphism-and-parameterization.md:186:7
               reset,	// polymorphism-and-parameterization.md:186:7
  input  [7:0] io_in1,	// polymorphism-and-parameterization.md:187:16
               io_in2,	// polymorphism-and-parameterization.md:187:16
  output [7:0] io_out	// polymorphism-and-parameterization.md:187:16
);

  Mod2 subMod (	// polymorphism-and-parameterization.md:192:24
    .in1 (io_in1),
    .in2 (io_in2),
    .out (io_out)
  );	// polymorphism-and-parameterization.md:192:24
endmodule