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.