- AUTHORS - A list of people who have historically contributed to gem5.
- LICENSE - The license terms that apply to gem5 as a whole, unless overridden by a more specific license.
- README - Some very basic information introducing gem5 and explaining how to get started.
- SConstruct - A part of the build system, as is the build_opts directory.
- build_opts - holds files that define default settings for build different build configurations. These include X86_FS and MIPS_SE, for instance.
- configs - Simulation configuration scripts which are written in python, described in more detail later. The files in this directory help make writing configurations easier by providing some basic prepackaged functionality, and include a few examples which can be used directly or as a starting point for your own scripts.
- ext - Things gem5 depends on but which aren’t actually part of gem5. Specifically, dependencies that are harder to find, not likely to be available, or where a particular version is needed.
-
src - gem5 source code.
-
arch - ISA implementations.
- generic - Common files for use in other ISAs.
- isa_parser.py - Parser that interprets ISA descriptions.
-
ISA directories - The files associated with the given ISA.
- OS directories - Code for supporting an ISA/OS combination, generally in SE mode.
- isa - ISA description files.
-
base - General data structures and facilities that could be useful for another project.
- loader - Code for loading binaries and reading symbol tables.
- stats - Code for keeping statistics and writing the data to a file or a database.
- vnc - VNC support.
- cpu - CPU models.
-
dev - Device models.
- ISA directories - Device models specific to the given ISA
- doxygen - Doxygen templates & output
-
kern - Operating system specific but architecture independent code (e.g. types of data structures).
- OS directories - Code specific to the given simulated operating system.
-
mem - Memory system models and infrastructure.
- cache - Code that implements a cache model in the classic memory system.
- ruby - Code that implements the ruby memory model.
- protocol - Ruby protocol definitions.
- slicc - The slicc compiler.
- python - Python code for configuration and higher level functions.
- sim - Code that implements basic, fundamental simulator functionality.
-
arch - ISA implementations.
-
system - Low level software like firmware or bootloaders for use in simulated systems.
- alpha - Alpha console and palcode.
- arm - A simple ARM bootloader.
-
tests - Files related to gem5’s regression tests.
- configs - General configurations used for the tests.
- test-progs - "Hello world" binaries for each ISA, other binaries are downloaded separately.
- quick, long - Quick and long regression inputs, reference outputs, and test specific configuration files, arranged per test.
- util - Utility scripts, programs and useful files which are not part of the gem5 binary but are generally useful when working on gem5.
Read the SConscript file before reading other files because this will give you an understanding of how
the files are linked to each other../build_opts/
Few files which set some variables used when building gem5. There is a file each for each ISA and each memory model./configs/boot/
RCS scripts mainly used for running benchmarks in FS mode. It covers all the SPEC benchmarks./configs/common/
Benchmarks.pyConfiguration script used for running benchmarks in FS mode. It will set the SysConfiguration.
SysConfig Class which contains scriptname, diskname and memsize. The disk containing benchmarks can be specified in this file for each ISA.
Benchmarks are defined as a key in a dict which is a list of SysConfigs
The first defined machine is the test system, the others are driving systems
Different SysConfigs are defined for different benchmarks - by setting the script, memsize
The scripts are located in ./configs/boot
CacheConfig.py
Configures the cache system for the system being simulated. Based on the command line
options given when gem5.opt is run, it creates the cache configuration to be used
Caches.py
Defines default parameters of L1, L2, IO, PageTableWalker Cache
CPUConfig.py
Builds the list of available CPU models and checks whether the option given on command line is an available CPU
FSConfig.py
Creates the different CPU models( MIPS, ALPHA, SPARC, etc.) for Full System simulation
Address Ports, Memory Busses etc.
O3ARMv7a.py
Defines the configuration parameters of ARMv7 CPU model. Various Functional Units, Branch Predictors, LSQs, caches, TLBs, etc.
All classes derive from generic clasess used in basic O3 model
Options.py
Defines all the command line options like –cpu-type, –cpu-number etc. system options, run duration options, checkpointing options, Fastforwarding and simpoint related materials, Benchmark options, FS options
Simulation.py
CPU models for restoring from checkpoint, initial fast-forwarding
Defines functions to set the simulation configuration like max time, fast-forward or detailed, creating checkpoints, restoring from checkpoints,
Switching CPUs, Actual Run after setting all these options, different types of switching are possible
SysPaths.py
Configures the paths for disks file, script file etc.
cpu2000.py
Configuration file for running SPEC2000 benchmarks
./config/examples
fs.pyScript to run FS simulation. Takes command line options and retrieves required information. Imports files from ./config/common
Similar files for testing memory system, running in SE mode. All of these import the files present in ./config/common
./config/ruby
Scripts related to ruby memory system./config/splash2
cluster.pyConfiguration related to running splash2 parallel benchmarks
Defines a class for each splash2 benchmark which inherits from LiveProcess class
Each class contains info about executable, cmd, input variables
Defines cache structure, number and type of clusters and number of cpus in a cluster - all obtained from command-line options
Creates a system, adds system-wide objects, connects them. Picks the correct benchmark, assigns the workload ans runs the simulation
run.py
Same as cluster.py with minor changes - clusters are not present
./config/topologies
Topologies for memory controllers./system
Low level software like firmware or bootloaders for use in simulated systems.alpha - Alpha console and palcode.
arm - A simple ARM bootloader.
BASE
./src/base/
types.hhDefines global host-dependent types:
Counter, Tick, and (indirectly) {int,uint}{8,16,32,64}_t.
Cycles class, Addr, MicroPC, MicroPC operations,
flags.hh
Defines flag class, functions for modifying flags like set, unset etc.
output.hh
Handles printing of data to an output stream
./src/base/stats/
types.hhNamespace Stats- Defines some basic stats types like Counter, VCounter, Result
info.hh
Info class to store information about various types of Stat like name, desc.
For Distributions, 2d-Vectors etc. we store min_val, max_val etc.
output.hh, text.hh, text.cc
Printing of stats to output stream
./src/base/vnc/
Vnc.pyVncInput class which derives from SimObject class
VncServer class which derives from VncInput
Some files related to handling input to vncserver and setting up a vncserver
./src/base/loader/
object_file.hhClass Object File - Architecture, OS. Mainly deals with how to read data from an object file
All files in this folder provide some classes which can be used to read various types of object files
refcnt.hh
RefCounted and RefCountingPtr classes which enable a class to be reference counted and provide automatic reference counting respectively.
ARCH
./src/arch/generic/
Generic classes which can be used to perform specific functions using any ISA like decode_cache, debug_fualts, memhelpers.hh./src/arch/arm/
./instsClasses which define what each instruction will do and to access information about instructions like branch, mem, misc, mult, etc.
./isa
./decoder
.isa files which define how to decode an arm.thumb instruction
./formats
.isa files which define various instruction formats like m5ops, branch, mem, etc.
./insts
Declarations of execution methods used for different types
PYTHON FOLDER
./m5/util/convert - Functions to convert a given string to numerical values related to memory size, clock period, network bandwidth etc../m5/util/attrdict - Modified Dict types with capability to add and delete attributes and a heirarchical structure
./m5/util/multidict - Dict of Dict and so on
./m5/util/orderdict - Ordered Dict
./m5/util/smartdict - Dictionary class that holds strings, but intelligently converts those strings to other types depending on their usage
./m5/util/sortedict -
./m5/util/region - Places data in regions and determines the type of overlap between two regions
./m5/util/init - Defines the error calls - panic, fatal, warn and inform. Several other utility functions
./m5/internal/params.py - A simple function to load all modules starting with m5.internal.params
./m5/internal/init - Imports some modules used in the simulator like core, event, stats, etc.
./m5/objects/init - Imports all modules starting with m5.objects
./m5/config.py - Directory settings for m5
./m5/debug.py - Extracting debug flags from m5 and printing them
./m5/event.py - Defines Event and Progress Event classes and related functions
./m5/main.py - The main script invoked when gem5 is run. Option parsing, gem5 interactive console , main function which prints info while gem5 is running
./m5/options.py Option parser
./m5/params.py - Parameter description classes. Each class has a _params dictionary which maps parameter names to Param objects. Functions which generate C++ code needed as a pre-requisite for declaring certain C++ objects. Defines several functions which deal with parameters
./m5/proxy.py - Proxy object support
./m5/ticks.py - Setting simulation accuracy and global frequency
./m5/SimObject.py -
./m5/simulate.py - Functions to instantiate Simobjects used in the system, create checkpoints, restore from checkpoints, switch cpus etc. In short, this script is responsible for starting and ending a simulation
./m5/stats/init - Initialization, resetting, dumping, et. of statistics
./swig Swig files for the main module defined in m5
SIMULATION FOLDER
./src/sim
./arguments.hh
Class arguments which has a thread context, number, data and methods which change or compare number field
./async.hh
Defines flags used to handle asynchronous simulator events
./byteswap.hh
Provides endianness coversion utility functions
./clocked_object.hh
The ClockedObject class extends the SimObject with a clock and accessor functions to relate ticks to the cycles of the object.
./core.hh
Core simulator functionality such as time information, output directory and exit events. Few simple functions
./eventq.hh
Class Event derives from Serializable and is a friend of class EventQueue. EventQueueManager
./serialize.hh
Serialization interface declarations
./debug.hh
Provides the definitions for some useful debugging functions. These are intended to be called from a debugger such as gdb
./drain.hh
Coordinates draining of a system. Drainable class. Functions to perform draining
./faults.hh
Various types of faults, their names and invoking functions.
./init.hh
EmbeddedPython, EmbeddedSwig structs. Some initialization function and handler functions
./insttracer.hh
Class InstRecord. Class InstTracer which mostly derives from SimObject
./microcoderom.hh
Generic stub microcode ROM ISAs can use if they don’t need anything more
./main.cc
Sets up Python and then calls initM5Python which loads the various embedded python modules into the python environment and then starts things running by calling m5Main.
./syscallreturn.hh
Class SyscallReturn. Successful and retval fields
./process.hh
All the details that are related to a process running on a cpu
class Process deriving from SimObject
class LiveProcess deriving from Process
./pseudo_inst.hh
PseudoInst namespace which defines several functions which behave like instructions and
perform several operations on a ThreadContext
./root.hh
The root SimObject in the simulation hierarchy
serialize.hh
Functions to create and restore from checkpoints
Serialize - create checkpoints Unserialize - Restore from checkpoints
./sim_events.hh
Event to terminate simulation at a particular cycle/instruction
CountedDrainEvent, CountedExitEvent
Used to terminate simulation after some special event
./sim_exit.hh
Functions which return the control to python after ending simulation
./sim_object.hh
Abstract superclass for simulation objects. Represents things that correspond to physical components and can be specified via the config file (CPUs, caches, etc.).
Methods used in starting and running a simulation
./simulate.hh
simulate method which returns SimLoopExitEvent
./stat_control.hh
Events related to dumping, resetting and registering statistics
./syscall_emul.hh
Defines objects used to emulate syscalls from the target application on the host machine.
./syscallreturn.hh
SysCallReturn Class which decodes the return value of a system call
./system.hh
Classes which define the system, ports, connections between system components
./tlb.hh
BaseTLB and GenericTLB classes
CPU
./src/cpu/
timebuf.hhTimeBuffer and Wire classes. Friends of each other. Wire contains TimeBuffer used for sending data between two objects
activity.hh
Activity Recorder helper class that informs the CPU if it can switch over to being idle or not
base.hh
CPUProgressEvent deriving from Event
BaseCPU deriving from MemObject
cpuevent.hh
CpuEvent class- Helps form a global list of events which need a pointer to a ThreadContext
decodecache.hh
Cache of recent Virtual Memory decodings and retrieval mechanisms from cache
exec_context.hh
ExecContext - Not a usable class. Only to demonstrate how ISA accesses CPU state
fudesc.hh
FuDesc and OpDesc classes which define a functional unit and its operations.
inst_seq.hh
Used to order instructions in the ready list
static_inst.hh
StaticInst class - Machine Inst, Flags, OpClass, Num of Src, Dest regs, Flag Accessor Functions
thread_context.hh
ThreadContext Class Accessor and Modifier functions for all registers, memory ports and most of the architectural state of a CPU. It is a virtual class.
So, we make use of ProxyThreadContext class to prevent the overhead of virtual callprevent the overhead of virtual calls
profile.hh
ProfileNode and FunctionProfile classes
thread_state.hh
Struct for holding general thread state that is needed across CPU models.
Very similar to thread_context with minor changes
smt.hh
Changing the thread state and priority for smt support
translation.hh
Captures the state of an address translation
WholeTranslationState and DataTranslation Classes
exectrace.hh
ExeTraceRecord and ExeTracer classes
simple_thread.hh
The SimpleThread object provides a combination of the ThreadState object and the ThreadContext interface
quiesce_event.hh
EndQuiesceEvent for timing out a quiesce instruction
intr_control.hh
Class to clear and post instructions of a particular CPU
legiontrace.hh
LegionTraceRecord and LegionTrace
pc_event.hh
PCEventQueue class which contains PCEvent class objects
base_dyn_inst.hh
Defines a dynamic instruction context
All the functions and processes that happen in a simple processor are defined in this class. Including functions for writing, reading memory, starting and ending translation etc.
Python Files
These files define the Python Objects, methods, files which point to the corresponding C++ object, using Cxx header and Cxx class variables
CHECKER
./src/cpu/checker/
thread_context.hhDerived ThreadContext class for use with the Checker. The template parameter is the ThreadContext class used by the specific CPU being verified. This CheckerThreadContext is then used by the main CPU in place of its usual ThreadContext class. It handles updating the checker’s state any time state is updated externally through the ThreadContext.
CheckerThreadContext - Actual Thread Context, Checker Thread, Checker CPU
cpu.hh
CheckerCPU class derives from BaseCPU class. BaseCPU is an abstract class. So CheckerCPU has most of the methods and members replicated
Templated Checker Class deriving from CheckerCPU which handles the checking/verifying functions
cpu_impl.hh
SIMPLE
./src/cpu/simple
base.hhBaseSimpleCPU derives from BaseCPU
CheckPcEventQueue - Seems to be the main function which moves instructions forward
Lots of stats variables
atomic.hh
AtomicSimpleCPU derives from BaseSimpleCPU
TickEvent Struct containing a CPU, TickEvent, Process methods
Main simulation loop - tick method
timing.hh
Class SplitMainSenderState to split memory access into two fragments
It has some TLB and memory access functions in addition to atomic functionality
PREDICTOR
./src/cpu/pred
btb.hhDefaultTLB class
Very simple and straight forward implementation of BTB
ras.hh
ReturnAddrStack class
sat_counter.hh
Private counter class for the internal saturating counters.
Implements an n bit saturating counter and provides methods to increment, decrement, and read it
bpred_unit.hh
Wrapper class to hold both the Branch Predictor and BTB
Predictor Histroy Struct to maintain information required to update BTB, RAS etc.
tournament.hh
Implements a tournament branch predictor
TournamentBP inherits from BPredUnit
2bit_local.hh
Implements a local predictor that uses the PC to index into a table of
counters. Contains a list of saturating counters.
OUT OF ORDER
./src/cpu/o3/
base_dyn_inst.ccMakes an explicit instantiation of BaseDynInst templated class with O3CPUImpl
checker.hh
Specific non-templated O3Checker derived class used for SimObject configuration.
comm.hh
Structures that define the information passed on from one stage to another stage of a superscalar pipeline
Each struct contains a list of DynInstPtr
Per thread variable like branchmisPredict, branchTaken etc.
A special structure which defines all backward communication - TimeBufStruct
commit.hh
Templated DefaultCommit Class
Has pointers to all the important structures and stages in the CPU
All the important architectural updates are handled
decode.hh
Because instructions are actually decoded when the StaticInst is created, this stage does not do much other than check any PC-relative branches
DefaultDecode - Very similar to DefaultCommit class
dep_graph.hh
Array of linked list that maintains the dependencies between producing instructions and consuming instructions
dyn_inst.hh
BaseO3DynInst deriving from BaseDynInst
fetch.hh
DefaultFetch Class
free_list.hh
SimpleFreeList class that simply holds the list of free integer and floating point registers.
fu_pool.hh
FUPool class which maintains a list of arrays of FUunits with a specific Capability
impl.hh
Implementation specific struct that defines several key types to the CPU, the stages within the CPU, the time buffers, and the DynInst.
inst_queue.hh
Instruction Queue which holds and schedules intructions
Gets information from FUs and MemUnit to track dependencies and resource availability
lsq_unit.hh
LSQUnit Class which implements Load and Store Queues
lsq.hh
LSQ class Templated with Impl
mem_dep_unit.hh
Memory Dependency Predictor
regfile.hh
Simple physical register file class.
Methods to set and read int and fp registers
scoreboard.hh
Implements a simple scoreboard to track which registers are ready
rob.hh
ROB class. The ROB is largely what drives squashing.
rename.hh
DefaultRename Class which handles both single threaded and SMT rename
thread_context.hh
Derived ThreadContext for use with O3CPU
thread_state.hh
O3ThreadState class that has various thread state, such as the status, the current instruction being processed, whether or not the thread has a trap pending or is being externally updated, the ThreadContext pointer, etc.
store_set.hh
Implements a store set predictor for determining if memory insts are dependent on each other
deriv.hh
DeriveO3CPU derived from templated FullO3CPU
iew.hh
DefaultIEW class which implements the iew stage of the pipeline
cpu_policy.hh
SimpleCPUPolicy Struct that defines the key classes to be used by the CPU.
All classes use the typedefs defined here to determine what are the classes of the other stages and communication buffers.
cpu.hh
BaseO3CPU deriving from BaseCPU
FullO3CPU deriving from BaseO3CPU
FullO3CPU class has each of the stages (fetch through commit)
within it, as well as all of the time buffers between stages.