README.md

# Trace Based Model (TBM)

## Project structure

### Executables:

- tbm/gentrace-spike.py - reads a Spike trace and reformat it. We expect to support
  other functional simulators, each of those will have its own gentrace-*.py
  file.
- tbm/import-riscv-opcodes.py - create and update pipe-maps.
- tbm/merge-counters.py - merges results from multiple runs of TBM.
- tbm/tbm.py - runs a trace in TBM; the main tool here.

### Python modules:

**NOTE:** currently TBM includes a single model for each of the building block
units. The intention is that other models will be added in the future to cover
uArchs that are not supported by the current models. interfaces.py defines (what
we expect to be) the API of the building blocks.

- tbm/buffered_queue.py - defines Queue, FIFO queue model.
- tbm/counter.py - performance counters.
- tbm/cpu.py - defines CPU, a cpu model (includes instances of FetchUnit, SchedUnit,
  ExecUnit, and MemorySystem).
- tbm/disassembler.py - bits we need to elaborate Spike traces.
- tbm/exec_unit.py - defines ExecUnit, an execution unit model (includes instances of
  ScalarPipe, VectorPipe, scoreboard.Preemptive and scoreboard.VecPreemptive).
- tbm/fetch_unit.py - defines FetchUnit.
- tbm/functional_trace.py - reads a trace (as generated by gentrace-*.py).
- tbm/instruction.py - defines Instruction, a data class representing a single
  instruction instance in the trace.
- tbm/interfaces.py - defines the internal API. This will be more important when we
  add different models (i.e. implementations) for the various units.
- tbm/memory_system.py - defines MemorySystem, a main memory and cache hierarchy model.
- tbm/scalar_pipe.py - defines ScalarPipe, a scalar functional unit model.
- tbm/sched_unit.py - defines SchedUnit, an issue queue model.
- tbm/scoreboard.py - defines Preemptive and VecPreemptive, scoreboard models.
- tbm/tbm_options.py - command line parsing for tbm.py.
- tbm/utilities.py - general purpose constructs.
- tbm/vector_pipe.py - defines VectorPipe, a vector functional unit model.

### TBM configuration files:

- config/instruction.fbs - FlatBuffer schema for the Instruction data class (used for
  saving elaborated traces). The FBInstruction.Instruction module is generated
  from this file.
- config/rvv-simple.yaml - a uArch configuration example.
- config/uarch.schema.json - JSON schema for uArch configuration files.
- pipe_maps/riscv/*.json - pipe-maps, mapping RISC-V opcodes to functional units.

### Build files:

- common.mk
- integration-tests.mk - runs tbm on some ML models.
- Makefile - builds things that are needed for tbm to run.
- riscv_tests.mk riscv_tests_isa.mk - runs tbm on tests from `$OUT/springbok/riscv-tests`.
- rvv_tests.mk - run tbm on tests from `$OUT/springbok/rvv_for_tbm/tests`.
- tbm.mk - rules for running tbm.


## How to use the make files

### Building TBM:

Before running any of the TBM tools you must run `make all`.

To update the RISC-V pipe-maps in `pipe_maps/riscv` run `make riscv_pipe_maps`.
This will import missing opcodes from `$ROOTDIR/toolchain/riscv-opcodes`, and
will remove spurious ones. New opcodes are mapped to "UNKNOWN". You can also
update individual RISC-V pipe-maps like this: `make pipe_maps/riscv/rv32a.json`.

To run a linter on all the Python files in `tbm/` run `make lint`.

To type-check all the Python scripts run `make type-check`. After running the
type checker you can merge inferred types back to the `.py` files by running
`make merge-pyi` to merge into all `.py` files, or `make merge-pyi-MOD` to
merge into `tbm/MOD.py`.

### Running tests from shodan

- `make -f integration-tests.mk integration_tests` - most of these tests are
actually not very good for integration testing as they take far too long to
complete.
- `make -f riscv_tests.mk riscv_tests_isa` - run some of the tests from `$ROOTDIR/out/springbok/riscv-tests/isa`.
- `make -f riscv_tests.mk riscv_tests_benchmarks` - run the tests from `$ROOTDIR/out/springbok/riscv-tests/benchmarks`.
- `make -f riscv_tests.mk riscv_tests` - run the two previous targets.
- `make -f riscv_tests.mk benchmarks` - runs the above benchmarks and generates
  the file `benchmarks.md` with all the results.
- `make -f rvv_tests.mk rvv_tests` - run the tests from `$ROOTDIR/out/springbok/rvv_for_tbm/tests/`.