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.76.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.76.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