README.md

# Trace Based Model (TBM)

## Code 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/tbm.py - runs a trace in TBM; the main tool here.
- tbm/merge-counters.py - merges results from multiple runs of TBM.

### 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.fbs - FlatBuffer schema for the Instruction data class (used for
  saving elaborated traces). The FBInstruction.Instruction module is generated
  from this file.
- 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.

### Other files:

- config/uarch.schema.json - JSON schema for uArch configuration files.
- config/rvv-simple.yaml - a uArch configuration example.