open source: getting ready to open source TBM
Mostly small improvements to the README.md.
Note the addition of <!--- BEGIN/END-INTERNAL --> tags, used by Copybara to
remove blocks of text.
Change-Id: I320f6c75e8b671474192553a65d9b5572b44b966
diff --git a/Makefile b/Makefile
index 26fd71a..dff498d 100644
--- a/Makefile
+++ b/Makefile
@@ -13,11 +13,13 @@
$(OUT_PACKAGES):
mkdir -p $@
+ifneq "$(wildcard $(ROOTDIR)/toolchain/riscv-opcodes)" ""
# Regenerate the pipe-maps for RISC-V, based on the opcodes from the
# riscv-opcodes repo. The associated pipes are copied from the old json file.
RISCV_EXTS := $(shell find $(ROOTDIR)/toolchain/riscv-opcodes -maxdepth 1 -name 'opcodes-*' -printf '%f\n' | cut -d- -f2-)
riscv_pipe_maps: $(RISCV_EXTS:%=pipe_maps/riscv/%.json)
.PHONY: riscv_pipe_maps
+endif
pipe_maps/riscv/%.json: $(ROOTDIR)/toolchain/riscv-opcodes/opcodes-%
$(PYTHON) $(IMPORT_RISCV_OPCODES) $(if $(wildcard $@),-m $@) -n $@.new $<
diff --git a/README.md b/README.md
index 7f8b003..521cba4 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,55 @@
# Trace Based Model (TBM)
+## What is TBM?
+
+TBM is a performance simulator, designed to get performance measurements very
+early in the design cycle of processors/accelerators. It provides a way for
+testing the impact of new design ideas, before any detailed implementation. In
+order to do hardware-software codesign, it is necessary to have a highly
+configurable, easily extended performance simulator that gives detailed,
+actionable feedback to hardware engineers about the bottlenecks of different
+microarchitectural options; that can give detailed, actionable feedback to
+software engineers about the performance of the inner loops of their code; and
+that can be used to evaluate a range of different design microarchitectural
+decisions. Having a configurable, and extensible, performance simulator enables
+the software and hardware engineers to have the conversations that are critical
+to hardware-software codesign and replaces guesswork and hunches with data.
+
+TBMs approach is to use an existing functional simulator to generate a
+functional trace and to build a “trace based model” (TBM) that models the
+control/scheduling logic of the microarchitecture but does not need to calculate
+the result of each instruction. The overall usage of a TBM: a functional
+simulator simulates execution of a program and generates a functional trace; TBM
+processes the functional trace using a microarchitectural model and produces
+information about the performance of the program on the microarchitecture being
+modeled. TBM is intended to be small and simple. Since it is only concerned with
+implementing the control/scheduling logic, it is possible to achieve high levels
+of code reuse and make it highly configurable.
+
## Project structure
+### Prerequisite:
+
+The make scripts expect the following environment variables and directory
+structure:
+
+* `ROOTDIR` should be set to the root directory of the shodan source tree.
+* `OUT` should be set to the directory where build artifacts should be created
+ (e.g. `$ROOTDIR/out`).
+* To use spike (RISC-V simulator), the spike executable should be in
+ `$OUT/host/spike/bin/spike`.
+* To update the RISC-V pipe-maps, the
+ [riscv-opcodes](https://github.com/riscv/riscv-opcodes) repo (commit
+ `6c34f60fe290613b7ba1d280b29a41179c399e69`) should be checked out at
+ `$ROOTDIR/toolchain/riscv-opcodes`.
+
### 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.
+- `tbm/gentrace-spike.py` - reads a Spike trace and reformat it.
+- `tbm/gentrace-renode.py` - reads a Renode trace and reformat it.
+- `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:
@@ -18,44 +58,46 @@
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
+- `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
+- `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/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
+- `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.
+- `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.
+- `Makefile` - builds things that are needed for tbm to run.
+- `common.mk`
+<!--- BEGIN-INTERNAL -->
+- `integration-tests.mk` - runs tbm on some ML models.
+- `riscv_tests.mk` `riscv_tests_isa.mk` - run tbm on tests from `$OUT/springbok/riscv-tests`.
+- `rvv_tests.mk` - runs tbm on tests from `$OUT/springbok/rvv_for_tbm/tests`.
+<!--- END-INTERNAL -->
+- `tbm.mk` - rules for running tbm.
## How to use the make files
@@ -78,9 +120,11 @@
### Running tests from shodan
+<!--- BEGIN-INTERNAL -->
- `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.
+<!--- END-INTERNAL -->
- `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.
