Signal Instrumenting

This is an experimental feature, on the instrumenting-sizes branch.

You have created a chisel circuit and you tried to figure out the right sizes for everything. Did you get it right. This feature provides a tool for figuring that out. When enabled, for every signal that is computed, the interpreter keeps the following information.

• The minimum value seen for the signal.
• The maximum value seen for the signal.
• The mean and standard deviation of the signal.
• A histogram with configurable number of bins, that records how the many times values appear with each bin. These values are printed out in a convenient CSV format.

How to use

When launching your test harness, using the Chisel-testers Driver (or subclasses of it), you can specify the following options.

  -fimbu, --fint-monitor-bit-usage
                           turn on bit monitoring, turns on stats for wires
  -fimof, --fint-monitor-output-file <name-of-output-file>
                           write monitoring stats to this file name instead of standard out
  -fimhb, --fint-monitor-histogram-bins <number-of-bins>
                           keeps this number of bins for histogram of bit usages, must be power of 2, default is none
  -fitt, --fint-monitor-track-temps
                           keep bit usage stats for temp nodes, default is false
  -fippms, --fint-pretty-print-monitor-stats
                           columnizes bit usage monitor reports

For example if you are running at test like this

  iotesters.Driver.execute(Array.empty, () => new MyCircuit) { dut =>
    new MyCircuitTester(dut)
  }

Change it like this to put the instrumentation in the file signal-data.csv keeping 16 bins of histogram data for all non-temporary signals.

  val myArgs = Array("-fimbu", "-fimof", "signals.csv", "-fimhb", "16")
  iotesters.Driver.execute(myArgs, () => new MyCircuit) { dut =>
    new MyCircuitTester(dut)
  }

When you run this program one of the messages you will get.

Bit Monitor report written to file /Volumes/UCB-BAR/chisel-testers/test_run_dir/examples.InstrumentingSpec756061723/InstrumentMe.signals.csv 

You will get something like this.

key,type,n,min,max,mean,stddev,bin0,bin1,bin2,bin3,bin4,bin5,bin6,bin7,bin8,bin9,bin10,bin11,bin12,bin13,bin14,bin15
io_sIn,sin<8>,256,-128,127,-0.5,0.2886729321699181,16,16,16,16,16,16,16,16,16,16,16,16,16,16,16,16
io_sOut,sin<8>,512,-128,127,-0.5,0.14433646608495904,32,32,32,32,32,32,32,32,32,32,32,32,32,32,32,32
io_sOutLower,sin<8>,519,-63,63,0.5260115606936394,0.07041993071346696,0,0,0,0,60,64,64,64,68,64,71,64,0,0,0,0
io_sOutUpper,sin<8>,519,-128,112,-6.381502890173411,0.14364841249000246,32,32,32,32,32,32,32,32,32,32,32,32,32,32,32,39
io_uIn,uint<8>,256,0,255,127.5,0.2886729321699181,16,16,16,16,16,16,16,16,16,16,16,16,16,16,16,16
io_uOut,uint<8>,512,0,255,127.5,0.14433646608495904,32,32,32,32,32,32,32,32,32,32,32,32,32,32,32,32
io_uOutLower,uint<8>,519,0,127,63.14258188824666,0.07095635841915023,64,64,71,64,64,64,64,64,0,0,0,0,0,0,0,0
io_uOutUpper,uint<8>,519,128,255,191.1425818882468,0.07095635841915027,0,0,0,0,0,0,0,0,64,64,71,64,64,64,64,64
reset,uint<1>,2,0,1,0.5,0.25,1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0

Add the pretty print flag with ```val myArgs = Array("-fimbu", "-fimof", "signals.csv", "-fimhb", "16", "-fippms") To get a more human readable form

key,              type,       n,     min,             max,            mean,          stddev,    bin0,    bin1,    bin2,    bin3,    bin4,    bin5,    bin6,    bin7,    bin8,    bin9,   bin10,   bin11,   bin12,   bin13,   bin14,   bin15
io_sIn          sin<8>,     256,    -128,             127,        -0.50000,         0.28867,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16
io_sOut         sin<8>,     512,    -128,             127,        -0.50000,         0.14434,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32
io_sOutLower    sin<8>,     519,     -63,              63,        -0.39114,         0.07018,       0,       0,       0,       0,      60,      64,      71,      64,      68,      64,      64,      64,       0,       0,       0,       0
io_sOutUpper    sin<8>,     519,    -128,             112,        -7.24470,         0.14170,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      39,      32,      32,      32,      32
io_uIn         uint<8>,     256,       0,             255,       127.50000,         0.28867,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16,      16
io_uOut        uint<8>,     512,       0,             255,       127.50000,         0.14434,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32,      32
io_uOutLower   uint<8>,     519,       0,             127,        63.46628,         0.07071,      64,      64,      64,      71,      64,      64,      64,      64,       0,       0,       0,       0,       0,       0,       0,       0
io_uOutUpper   uint<8>,     519,     128,             255,       191.46628,         0.07071,       0,       0,       0,       0,       0,       0,       0,       0,      64,      64,      64,      71,      64,      64,      64,      64
reset          uint<1>,       2,       0,               1,         0.50000,         0.25000,       1,       1,       0,       0,       0,       0,       0,       0,       0,       0,       0,       0,       0,       0,       0,       0