gem5 v25.1: Using the gem5 standard library configuration scripts

The introduction of the gem5 standard library has changed the way that gem5 configuration scripts are written. Examples of these configuration scripts for the gem5 standard library are located at configs/example/gem5_library.

A brief look at the directory structure is as follows:

gem5_library
    |
    |- caches       #contains a configuration script for the octopi cache
    |
    |- checkpoints  #scripts for taking and restoring from checkpoints
    |
    |- dramsys      #scripts for using gem5 with dramsys
    |
    |- looppoints   #scripts for taking and restoring from looppoints
    |
    |- multisim     #scripts for launching multiple simulations at once using multisim
    |
    |- spatter_gen  #scripts for SpatterGen
    |
    |- (various example configuration scripts not sorted into a subdirectory)

The example configuration scripts placed directly in the gem5_library directory are similar to what you’ve seen in previous parts of Learning gem5, but with more variety, e.g. different ISAs, boards, and workloads. The source for these scripts can be viewed here.

Using the default configuration scripts

In this chapter, we’ll explore using the default configuration scripts that come with gem5. gem5 ships with many configuration scripts that allow you to use gem5 very quickly. However, a common pitfall is to use these scripts without fully understanding what is being simulated. It is important when doing computer architecture research with gem5 to fully understand the system you are simulating. This chapter will walk you through some important options and parts of the default configuration scripts.

In the last few chapters you have created your own configuration scripts from scratch. This is very powerful, as it allows you to specify every single system parameter. However, some systems are very complex to set up (e.g., a full-system ARM or x86 machine). Luckily, the gem5 developers have provided many scripts to bootstrap the process of building systems.

Note that while these configuration files are now deprecated, they have been used for many years for architecture research. As a result, we will use these throughout the semester.

Using `se.py` and `fs.py`

In this section, I’ll discuss some of the common options that can be passed on the command line to se.py and fs.py. More details on how to run full-system simulation can be found in the full-system simulation chapter. Here I’ll discuss the options that are common to the two files.

Most of the options discussed in this section are found in Options.py and are registered in the function addCommonOptions. This section does not detail all of the options. To see all of the options, run the configuration script with --help, or read the script’s source code.

First, let’s simply run the hello world program without any parameters:

./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello

And we get the following as output: gem5 Simulator System. https://www.gem5.org gem5 is copyrighted software; use the –copyright option for details.

gem5 version 25.0.0.1
gem5 compiled Sep 13 2025 13:46:50
gem5 started Sep 14 2025 07:00:51
gem5 executing on fa25-cs433-xxx.cs.illinois.edu, pid 402422
command line: ./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello

warn: The se.py script is deprecated. It will be removed in future releases of  gem5.
Global frequency set at 1000000000000 ticks per second
src/mem/dram_interface.cc:690: warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes)
src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated.
system.remote_gdb: Listening for connections on port 7000
**** REAL SIMULATION ****
Hello world!
Exiting @ tick 2920000 because exiting with last active thread context
Simulated exit code not 0! Exit code is 13

However, this isn’t a very interesting simulation at all! By default, gem5 uses the atomic CPU and uses atomic memory accesses, so there’s no real timing data reported! To confirm this, you can look at m5out/config.ini. The CPU is shown on line 53:

[system.cpu]
type=BaseAtomicSimpleCPU
children=decoder interrupts isa mmu power_state tracer workload
branchPred=Null
checker=Null
clk_domain=system.cpu_clk_domain
cpu_id=0
decoder=system.cpu.decoder
do_checkpoint_insts=true
do_statistics_insts=true

To actually run gem5 in timing mode, let’s specify a CPU type. While we’re at it, we can also specify sizes for the L1 caches.

./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB

gem5 Simulator System.  https://www.gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 version 25.0.0.1
gem5 compiled Sep 13 2025 13:46:50
gem5 started Sep 14 2025 07:05:04
gem5 executing on fa25-cs433-xxx.cs.illinois.edu, pid 402488
command line: ./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB

warn: The se.py script is deprecated. It will be removed in future releases of  gem5.
Global frequency set at 1000000000000 ticks per second
src/mem/dram_interface.cc:690: warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes)
src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated.
system.remote_gdb: Listening for connections on port 7000
**** REAL SIMULATION ****
Hello world!
Exiting @ tick 333559000 because exiting with last active thread context
Simulated exit code not 0! Exit code is 13

Now, let’s check the config.ini file and make sure that these options propagated correctly to the final system. If you search m5out/config.ini for “cache”, you’ll find that no caches were created! Even though we specified the size of the caches, we didn’t specify that the system should use caches, so they weren’t created. The correct command line should be:

./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB --caches

gem5 Simulator System.  https://www.gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 version 25.0.0.1
gem5 compiled Sep 13 2025 13:46:50
gem5 started Sep 14 2025 07:06:15
gem5 executing on fa25-cs433-xxx.cs.illinois.edu, pid 402495
command line: ./build/ARM/gem5.opt configs/deprecated/example/se.py --cmd=tests/test-progs/hello/bin/arm/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB --caches

warn: The se.py script is deprecated. It will be removed in future releases of  gem5.
warn: Base 10 memory/cache size 16kB will be cast to base 2 size 16KiB.
warn: Base 10 memory/cache size 64kB will be cast to base 2 size 64KiB.
Global frequency set at 1000000000000 ticks per second
src/mem/dram_interface.cc:690: warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes)
src/base/statistics.hh:279: warn: One of the stats is a legacy stat. Legacy stat is a stat that does not belong to any statistics::Group. Legacy stat is deprecated.
system.remote_gdb: Listening for connections on port 7000
**** REAL SIMULATION ****
Hello world!
Exiting @ tick 29383000 because exiting with last active thread context
Simulated exit code not 0! Exit code is 13

On the last line, we see that the total time went from 333559000 ticks to 29383000, much faster! Looks like caches are probably enabled now. But, it’s always a good idea to double check the config.ini file.

[system.cpu.dcache]
type=Cache
children=power_state replacement_policy tags
addr_ranges=0:18446744073709551615
assoc=2
clk_domain=system.cpu_clk_domain
clusivity=mostly_incl
compressor=Null
data_latency=2
demand_mshr_reserve=1
eventq_index=0
is_read_only=false
max_miss_count=0
move_contractions=true
mshrs=4
power_model=
power_state=system.cpu.dcache.power_state
prefetch_on_access=false
prefetcher=Null
replace_expansions=true
replacement_policy=system.cpu.dcache.replacement_policy
response_latency=2
sequential_access=false
size=65536
system=system
tag_latency=2
tags=system.cpu.dcache.tags
tgts_per_mshr=20
warmup_percentage=0
write_allocator=Null
write_buffers=8
writeback_clean=false
cpu_side=system.cpu.dcache_port
mem_side=system.membus.cpu_side_ports[2]

Some common options `se.py` and `fs.py`

All of the possible options are printed when you run:

./build/ARM/gem5.opt configs/deprecated/example/se.py --help

Below are a few important options from that list:

--cpu-type=CPU_TYPE
- The type of cpu to run with. This is an important parameter to always set. The default is atomic, which doesn’t perform a timing simulation.
--sys-clock=SYS_CLOCK
- Top-level clock for blocks running at system speed.
--cpu-clock=CPU_CLOCK
- Clock for blocks running at CPU speed. This is separate from the system clock above.
--mem-type=MEM_TYPE
- Type of memory to use. Options include different DDR memories, and the ruby memory controller.
--caches
- Perform the simulation with classic caches.
--l2cache
- Perform the simulation with an L2 cache, if using classic caches.
--ruby
- Use Ruby instead of the classic caches as the cache system simulation.
-m TICKS, --abs-max-tick=TICKS
- Run to absolute simulated tick specified including ticks from a restored checkpoint. This is useful if you only want simulate for a certain amount of simulated time.
-I MAXINSTS, --maxinsts=MAXINSTS
- Total number of instructions to simulate (default: run forever). This is useful if you want to stop simulation after a certain number of instructions has been executed.
-c CMD, --cmd=CMD
- The binary to run in syscall emulation mode.
-o OPTIONS, --options=OPTIONS
- The options to pass to the binary, use ” ” around the entire string. This is useful when you are running a command which takes options. You can pass both arguments and options (e.g., –whatever) through this variable.
--output=OUTPUT
- Redirect stdout to a file. This is useful if you want to redirect the output of the simulated application to a file instead of printing to the screen. Note: to redirect gem5 output, you have to pass a parameter before the configuration script.
--errout=ERROUT
- Redirect stderr to a file. Similar to above.

gem5 v25.1: Using the gem5 standard library configuration scripts

Using the default configuration scripts

Using se.py and fs.py

Some common options se.py and fs.py

Using `se.py` and `fs.py`

Some common options `se.py` and `fs.py`