What is the Firrtl Repl

What is a REPL?

It stands for a read-evaluate-print-loop. The firrtl interpreters repl is an interactive shell supporting an peek-poke-step interface used by the InterpretiveTester.

Essentially the repl allows a user to load a firrtl circuit, poke values into it's inputs (its registers too) and peek it's output values, issuing step commands to advance a virtual clock and advance register values. The repl allows a growing set of instructions that expose the circuit simulation via dependency analysis implemented in the interpreter. There are instructions to control the functioning of the interpreter and what it displays.

For small to medium circuits it is very convenient way to debug a circuit that is not behaving as desired.

For a in-depth tutorial check out: Chisel3 Debugging-with-the-Interpreter-REPL

How to start it up. There are two main ways to start the firrtl-repl

From the command line using ./frepl.sh

Use ./frepl.sh --help to see all the command line options supported Use ./frepl.sh --firrtl-source-file myfirrtlfile.fir to launch a repl loading the specified firrtl file.

Programmatically

The direct command line example is not usually the best way to launch the repl. It only works if you have a firrtl file. More often the user has a Chisel circuit contained in a .scala file. The following will show how to launch the repl in code. For example if I have some simple circuit in a file like Add3.scala

package mypackage

import chisel3._
class Add3 extends Module {
  val io = IO(new Bundle {
    val in = Input(UInt(width = 16))
    val out = Output(UInt(width = 16))
  })
  io.out := io.in +% 3.U
}

It needs a callable main, so add one as follows. Insert into Add3.scala something like this.

object Add3 {
  def main(args: Array[String]) {
    val optionsManager = new iotestesrs.ReplOptionsManager
    if(optionsManager.parse(args)) {
      iotesters.Driver.executeFirrtlRepl(() => new RealGCD2, optionsManager)
    }
  }
}

The optionsManager knows how to parse command line arguments in order to set the various options that the repl, chisel and firrtl need. To run the repl now, just execute from the command line

prompt> sbt 'run-main mypackage.Add3'

This will place you in the repl. Type help and see what you can do.