gem5

https://www.gem5.org/documentation/
Admin
gem5 is a modular platform for computer architecture research, providing a simulation infrastructure...
Tokens:310,159
Snippets:3,164
Trust Score:9.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Benchmark Dependencies with Apt-get

Source: https://www.gem5.org/documentation/gem5art/main/disks

Example of installing a package like 'gfortran' using apt-get within a post-installation script. Assumes a password is provided for sudo.

```bash
echo '12345' | sudo apt-get install gfortran;
```

--------------------------------

### Install Ubuntu Server using QEMU

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Boots a QEMU virtual machine from an Ubuntu installation ISO to install the OS onto a pre-created disk image. Ensure sufficient memory is allocated and avoid logical partitions during installation.

```bash
qemu-system-x86_64 -hda ../gem5-fs-testing/ubuntu-test.img -cdrom ubuntu-16.04.1-server-amd64.iso -m 1024 -enable-kvm -boot d

```

--------------------------------

### Install QEMU

Source: https://www.gem5.org/documentation/gem5art/main/disks

Installs QEMU on Debian-based systems using apt-get. This is a prerequisite for using QEMU with Packer.

```bash
sudo apt-get install qemu

```

--------------------------------

### Example: Build gem5 with ALL ISA and opt variant

Source: https://www.gem5.org/documentation/general_docs/building

Example of building gem5 with all ISAs and the 'opt' build variant using 4 parallel threads.

```bash
scons build/ALL/gem5.opt -j 4

```

--------------------------------

### Example Makefile for C++ Application

Source: https://www.gem5.org/documentation/general_docs/m5ops

A complete Makefile example demonstrating how to compile and link a C++ application with m5.

```makefile
TARGET_ISA=x86

GEM5_HOME=$(realpath ./) 
$(info   GEM5_HOME is $(GEM5_HOME))

CXX=g++

CFLAGS=-I$(GEM5_HOME)/include

LDFLAGS=-L$(GEM5_HOME)/util/m5/build/$(TARGET_ISA)/out -lm5

OBJECTS= hello_world

all: hello_world

hello_world:
	$(CXX) -o $(OBJECTS) hello_world.cpp $(CFLAGS) $(LDFLAGS)

clean:
	rm -f $(OBJECTS)
```

--------------------------------

### Install and Install Pre-commit

Source: https://www.gem5.org/documentation/general_docs/common-errors

Install the pre-commit tool and set it up for your gem5 project. This ensures code style checks are performed automatically before commits.

```bash
pip install pre-commit
pre-commit install
```

--------------------------------

### Install QEMU and related tools on Ubuntu

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Installs QEMU and necessary virtualization and networking tools on Ubuntu systems. This is a prerequisite for using QEMU for disk image management.

```bash
sudo apt-get install qemu-kvm libvirt-bin ubuntu-vm-builder bridge-utils

```

--------------------------------

### Install Required Development Libraries

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

This command installs the necessary ProtocolBuffer development libraries and compiler, which can resolve protobuf-related build errors.

```bash
sudo apt update
sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev

```

--------------------------------

### Setup Ruby System Components

Source: https://www.gem5.org/documentation/learning_gem5/part3/configuration

The setup function initializes the network, controllers, and sequencers, then connects them. It configures system ports and connects CPUs to their respective sequencers and cache ports, with specific handling for x86 and ARM ISAs.

```python
def setup(self, system, cpus, mem_ctrls):
    self.network = MyNetwork(self)

    self.number_of_virtual_networks = 3
    self.network.number_of_virtual_networks = 3

    self.controllers =
        [L1Cache(system, self, cpu) for cpu in cpus] + \
        [DirController(self, system.mem_ranges, mem_ctrls)]

    self.sequencers = [RubySequencer(version = i,
                            # I/D cache is combined and grab from ctrl
                            icache = self.controllers[i].cacheMemory,
                            dcache = self.controllers[i].cacheMemory,
                            clk_domain = self.controllers[i].clk_domain,
                            ) for i in range(len(cpus))]

    for i,c in enumerate(self.controllers[0:len(self.sequencers)]):
        c.sequencer = self.sequencers[i]

    self.num_of_sequencers = len(self.sequencers)

    self.network.connectControllers(self.controllers)
    self.network.setup_buffers()

    self.sys_port_proxy = RubyPortProxy()
    system.system_port = self.sys_port_proxy.slave

    for i,cpu in enumerate(cpus):
        cpu.icache_port = self.sequencers[i].slave
        cpu.dcache_port = self.sequencers[i].slave
        isa = buildEnv['TARGET_ISA']
        if isa == 'x86':
            cpu.interrupts[0].pio = self.sequencers[i].master
            cpu.interrupts[0].int_master = self.sequencers[i].slave
            cpu.interrupts[0].int_slave = self.sequencers[i].master
        if isa == 'x86' or isa == 'arm':
            cpu.itb.walker.port = self.sequencers[i].slave
            cpu.dtb.walker.port = self.sequencers[i].slave


```

--------------------------------

### Download and install gem5 guest tools

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Downloads and installs precompiled binaries for gem5 guest tools, simplifying the integration of gem5's host-guest communication features. This is an alternative to manually updating the init script.

```bash
wget http://cs.wisc.edu/~powerjg/files/gem5-guest-tools-x86.tgz
tar xzvf gem5-guest-tools-x86.tgz
cd gem5-guest-tools/
sudo ./install

```

--------------------------------

### Boot Ubuntu from disk image with QEMU

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Boots the QEMU virtual machine from the installed Ubuntu disk image. This command is used after the OS installation is complete, removing the boot-from-CD option.

```bash
qemu-system-x86_64 -hda ../gem5-fs-testing/ubuntu-test.img -cdrom ubuntu-16.04.1-server-amd64.iso -m 1024 -enable-kvm

```

--------------------------------

### Install Protocol Buffers and Google Perftools on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs Protocol Buffers and Google Perftools libraries on Ubuntu. These are optional but used for trace generation and playback.

```bash
sudo apt install libprotobuf-dev protobuf-compiler libgoogle-perftools-dev

```

--------------------------------

### gem5 Run Script Example

Source: https://www.gem5.org/documentation/gem5art/tutorials/boot-tutorial

Example of how to run gem5 with a compiled Linux kernel and disk image, specifying CPU type, memory system, number of CPUs, and boot type.

```bash
gem5/build/X86/gem5.opt configs/run_exit.py [path to the Linux kernel] [path to the disk image] kvm classic 4 init
```

--------------------------------

### gem5 Simulation Output Example

Source: https://www.gem5.org/documentation/learning_gem5/part1/extending_configs

Example output from a gem5 simulation, showing startup messages, simulation progress, and exit information. This is useful for verifying simulation runs.

```text
gem5 Simulator System.  http://gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 compiled Oct  3 2019 16:02:35
gem5 started Oct  6 2019 13:22:25
gem5 executing on amarillo, pid 77129
command line: build/ARM/gem5.opt configs/tutorial/simple.py

Global frequency set at 1000000000000 ticks per second
warn: DRAM device capacity (8192 Mbytes) does not match the address range assigned (512 Mbytes)
0: system.remote_gdb: listening for remote gdb on port 7002
Beginning simulation!
info: Entering event queue @ 0.  Starting simulation...
info: Increasing stack size by one page.
warn: readlink() called on '/proc/self/exe' may yield unexpected results in various settings.
      Returning '/home/jtoya/gem5/cpu_tests/benchmarks/bin/arm/Bubblesort'
-50000
Exiting @ tick 258647411000 because exiting with last active thread context

```

--------------------------------

### m5term Interactive Session Example

Source: https://www.gem5.org/documentation/general_docs/fullsystem/m5term

An example demonstrating an interactive session with m5term connected to a gem5 simulation. It shows the initial console output and a sample 'ls' command execution within the simulated environment.

```bash
% m5term localhost 3456
==== m5 slave console: Console 0 ====
M5 console
Got Configuration 127
memsize 8000000 pages 4000
First free page after ROM 0xFFFFFC0000018000
HWRPB 0xFFFFFC0000018000 l1pt 0xFFFFFC0000040000 l2pt 0xFFFFFC0000042000 l3pt_rpb 0xFFFFFC0000044000 l3pt_kernel 0xFFFFFC0000048000 l2reserv 0xFFFFFC0000046000
CPU Clock at 2000 MHz IntrClockFrequency=1024
Booting with 1 processor(s)
...
...
VFS: Mounted root (ext2 filesystem) readonly.
Freeing unused kernel memory: 480k freed
init started:  BusyBox v1.00-rc2 (2004.11.18-16:22+0000) multi-call binary

PTXdist-0.7.0 (2004-11-18T11:23:40-0500)

mounting filesystems...
EXT2-fs warning: checktime reached, running e2fsck is recommended
loading script...
Script from M5 readfile is empty, starting bash shell...
# ls
benchmarks  etc         lib         mnt         sbin        usr
bin         floppy      lost+found  modules     sys         var
dev         home        man         proc        tmp         z
#

```

--------------------------------

### Begin Simulation Execution

Source: https://www.gem5.org/documentation/learning_gem5/part1/simple_config

Starts the gem5 simulation and captures the exit event.

```Python
print("Beginning simulation!")
exit_event = m5.simulate()

```

--------------------------------

### Example Debug Output

Source: https://www.gem5.org/documentation/learning_gem5/part2/debugging

This is an example of the output you might see when running gem5 with the 'HelloExample' debug flag enabled. It shows the custom debug message printed by your SimObject.

```text
gem5 Simulator System.  http://gem5.org
gem5 is copyrighted software; use the --copyright option for details.

gem5 compiled Jan  4 2017 09:40:10
gem5 started Jan  4 2017 09:41:01
gem5 executing on chinook, pid 29078
command line: build/X86/gem5.opt --debug-flags=HelloExample configs/learning_gem5/part2/run_hello.py

Global frequency set at 1000000000000 ticks per second
      0: hello: Created the hello object
Beginning simulation!
info: Entering event queue @ 0.  Starting simulation...
Exiting @ tick 18446744073709551615 because simulate() limit reached

```

--------------------------------

### gem5 Build Output Example

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

This is an example of the output you can expect when compiling gem5 version 24.1 or later. It includes dependency checks, configuration details, and the compilation progress of various source files and linking steps.

```text
    scons: Reading SConscript files ...
    Mkdir("/local.chinook/gem5/gem5-tutorial/gem5/build/ALL/gem5.build")
    Checking for linker -Wl,--as-needed support... (cached) yes
    Checking for compiler -gz support... (cached) yes
    Checking for linker -gz support... (cached) yes
    Info: Using Python config: python3-config
    Checking for C header file Python.h... (cached) yes
    Checking Python version... (cached) 3.12.3
    Checking for accept(0,0,0) in C++ library None... (cached) yes
    Checking for zlibVersion() in C++ library z... (cached) yes
    Checking for C library tcmalloc_minimal... (cached) yes
    Building in /home/bees/gem5-4th-worktree/build/ALL
    "build_tools/kconfig_base.py" "/home/bees/gem5-4th-worktree/build/ALL/gem5.build/Kconfig" "/home/bees/gem5-4th-worktree/src/Kconfig" 
    Checking for C header file fenv.h... (cached) yes
    Checking for C header file png.h... (cached) yes
    Checking for clock_nanosleep(0,0,NULL,NULL) in C library None... (cached) yes
    Checking for C header file valgrind/valgrind.h... (cached) yes
    Checking for pkg-config package hdf5-serial... (cached) yes
    Checking for H5Fcreate("", 0, 0, 0) in C library hdf5... (cached) yes
    Checking for H5::H5File("", 0) in C++ library hdf5_cpp... (cached) yes
    Checking for pkg-config package protobuf... (cached) yes
    Checking for shm_open("/test", 0, 0) in C library None... (cached) yes
    Checking for backtrace_symbols_fd((void *)1, 0, 0) in C library None... (cached) yes
    Checking size of struct kvm_xsave ... (cached) yes
    Checking for C header file capstone/capstone.h... (cached) yes
    Checking for C header file linux/kvm.h... (cached) yes
    Checking for timer_create(CLOCK_MONOTONIC, NULL, NULL) in C library None... (cached) yes
    Checking for member exclude_host in struct perf_event_attr...(cached) yes
    Checking for C header file linux/if_tun.h... (cached) yes 
    Checking whether __i386__ is declared... (cached) no
    Checking whether __x86_64__ is declared... (cached) yes
    Checking for compiler -Wno-self-assign-overloaded support... (cached) yes
    Checking for linker -Wno-free-nonheap-object support... (cached) yes
    BUILD_TLM not set, not building CHI-TLM integration

    scons: done reading SConscript files.
    scons: Building targets ...
    [     CXX] ALL/base/Graphics.py.cc -> .o
    [    LINK]  -> ALL/gem5py_m5
    [     CXX] src/base/atomicio.cc -> ALL/base/atomicio.o
    [     CXX] src/base/bitfield.cc -> ALL/base/bitfield.o

     ....
     .... <lots of output>
     ....
 [SO Param] m5.objects.Uart, Uart8250 -> ALL/params/Uart8250.hh
 [     CXX] ALL/python/_m5/param_SimpleUart.cc -> .o
 [     CXX] ALL/enums/TerminalDump.cc -> .o
 [     CXX] ALL/python/_m5/param_Uart8250.cc -> .o
 [     CXX] src/dev/serial/serial.cc -> ALL/dev/serial/serial.o
 [     CXX] src/dev/serial/simple.cc -> ALL/dev/serial/simple.o
 [     CXX] src/dev/serial/terminal.cc -> ALL/dev/serial/terminal.o
 [     CXX] src/dev/serial/uart.cc -> ALL/dev/serial/uart.o
 [     CXX] src/dev/serial/uart8250.cc -> ALL/dev/serial/uart8250.o
 [     CXX] ALL/debug/Terminal.cc -> .o
 [     CXX] ALL/debug/TerminalVerbose.cc -> .o
 [     CXX] ALL/debug/Uart.cc -> .o
 [     CXX] ALL/python/m5/defines.py.cc -> .o
 [     CXX] ALL/python/m5/info.py.cc -> .o
 [     CXX] src/base/date.cc -> ALL/base/date.o
 [    LINK]  -> ALL/gem5.opt
scons: done building targets.
```

--------------------------------

### Enter chroot environment for application installation

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Command to change the root directory to the gem5 simulated disk image (mnt) and start a bash shell. This allows installing applications as if on a native system.

```bash
> sudo /usr/sbin/chroot mnt /bin/bash

```

--------------------------------

### Start Celery Worker for gem5 Tasks

Source: https://www.gem5.org/documentation/gem5art/main/tasks

This command starts a Celery worker instance for gem5art tasks. It enables events and uses autoscale to manage the number of workers. Ensure RabbitMQ is installed and running as a message broker.

```bash
celery -E -A gem5art.tasks.celery worker --autoscale=[number of workers],0
```

--------------------------------

### Configure Post-Installation Scripts

Source: https://www.gem5.org/documentation/gem5art/tutorials/parsec-tutorial

Sets up system services and the gem5 m5 binary after the disk image is installed. It moves necessary files to their system locations and creates a symbolic link for the m5 binary.

```bash
#!/bin/bash
echo 'Post Installation Started'

mv /home/gem5/serial-getty@.service /lib/systemd/system/

mv /home/gem5/m5 /sbin
ln -s /sbin/m5 /sbin/gem5

# copy and run outside (host) script after booting
cat /home/gem5/runscript.sh >> /root/.bashrc

echo 'Post Installation Done'

```

--------------------------------

### SwitchableProcessor Class

Source: https://www.gem5.org/documentation/general_docs/stdlib_api/gem5.components.processors.switchable_processor.html

The SwitchableProcessor class allows for the setup of switchable processors using SimpleCores. It is designed to be inherited from, with SimpleSwitchableCPU serving as an example.

```APIDOC
## Class: SwitchableProcessor

### Description
This class can be used to setup a switchable processor/processors on a system using SimpleCores. Though this class can be used directly, it is best inherited from. See SimpleSwitchableCPU for an example of this.

### Methods

#### `get_cores()`
- **Description**: Retrieves the list of cores managed by this processor.
- **Returns**: A list of `AbstractCore` objects.

#### `get_num_cores()`
- **Description**: Returns the total number of cores managed by this processor.
- **Returns**: An integer representing the number of cores.

#### `incorporate_processor(_board: AbstractBoard)`
- **Description**: Incorporates this processor into a given board.
- **Parameters**:
  - `_board` (AbstractBoard) - The board to incorporate the processor into.
- **Returns**: None.

#### `switch_to_processor(_switchable_core_key: str)`
- **Description**: Switches the active processor configuration to one specified by the key.
- **Parameters**:
  - `_switchable_core_key` (str) - The key identifying the desired switchable core configuration.
```

--------------------------------

### Fatal Error Example

Source: https://www.gem5.org/documentation/general_docs/common-errors

A fatal error indicates an invalid simulation configuration. The error message includes the source file, which is a good starting point for debugging.

```text
build/ALL/cpu/base.cc:186: fatal: Number of processes (cpu.workload) (0) assigned to the CPU does not equal number of threads (1).

```

--------------------------------

### Run Hello World with Timing CPU and Cache Sizes

Source: https://www.gem5.org/documentation/learning_gem5/part1/example_configs

Runs the 'hello world' program using the TimingSimpleCPU and specifies sizes for L1 data and instruction caches. This enables timing simulation but does not enable caches by default.

```bash
build/X86/gem5.opt configs/example/se.py --cmd=tests/test-progs/hello/bin/x86/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB

```

--------------------------------

### Run Hello World with Timing CPU and Caches Enabled

Source: https://www.gem5.org/documentation/learning_gem5/part1/example_configs

Executes the 'hello world' program using the TimingSimpleCPU, specifies L1 cache sizes, and explicitly enables caches using the --caches option. This ensures that caches are created and used during the simulation.

```bash
build/X86/gem5.opt configs/example/se.py --cmd=tests/test-progs/hello/bin/x86/linux/hello --cpu-type=TimingSimpleCPU --l1d_size=64kB --l1i_size=16kB --caches

```

--------------------------------

### Using Debugger Breakpoints with gem5

Source: https://www.gem5.org/documentation/general_docs/debugging_and_testing/debugging/debugger_based_debugging

This example demonstrates starting gem5 under gdb and setting a breakpoint using the --debug-break parameter. It shows how to inspect the current tick and continue execution.

```gdb
% gdb m5/build/ALL/gem5.debug
GNU gdb 6.1
Copyright 2002 Free Software Foundation, Inc.
[...] 
(gdb) run --debug-break=2000 configs/run.py
Starting program: /z/stever/bk/m5/build/ALL/gem5.debug --debug-break=2000 configs/run.py
M5 Simulator System
[...] 
warn: Entering event queue @ 0.  Starting simulation...

Program received signal SIGTRAP, Trace/breakpoint trap.
0xffffe002 in ?? ()
(gdb) p curTick
$1 = 2000
(gdb) c
Continuing.

(gdb) call schedBreak(3000)
(gdb) c
Continuing.

Program received signal SIGTRAP, Trace/breakpoint trap.
0xffffe002 in ?? ()
(gdb) p _curTick
$3 = 3000
(gdb)
```

--------------------------------

### MSI Protocol Trace Example

Source: https://www.gem5.org/documentation/learning_gem5/part3/MSIdebugging

This protocol trace snippet shows various events and state transitions for cache line 0x4ac0 within the MSI protocol, including Load, Store, GetS, GetM, and acknowledgments.

```text
4541   0    L1Cache         Replacement   MI_A>MI_A   [0x4ac0, line 0x4ac0]
4542   0    L1Cache              PutAck   MI_A>I      [0x4ac0, line 0x4ac0]
4549   0  Directory              MemAck   MI_M>I      [0x4ac0, line 0x4ac0]
4641   0        Seq               Begin       >       [0x4aec, line 0x4ac0] LD
4652   0    L1Cache                Load      I>IS_D   [0x4ac0, line 0x4ac0]
4657   0  Directory                GetS      I>S_M    [0x4ac0, line 0x4ac0]
4669   0  Directory             MemData    S_M>S      [0x4ac0, line 0x4ac0]
4674   0        Seq                Done       >       [0x4aec, line 0x4ac0] 33 cycles
4674   0    L1Cache       DataDirNoAcks   IS_D>S      [0x4ac0, line 0x4ac0]
5321   0        Seq               Begin       >       [0x4aec, line 0x4ac0] ST
5322   0    L1Cache               Store      S>SM_AD  [0x4ac0, line 0x4ac0]
5327   0  Directory                GetM      S>M_M    [0x4ac0, line 0x4ac0]
```

--------------------------------

### Initialize Git Repository and Remote

Source: https://www.gem5.org/documentation/gem5art/tutorials/boot-tutorial

Create the main project directory, navigate into it, and initialize a git repository. Add a remote origin for hosting the repository.

```bash
mkdir boot-tests
cd boot-tests
git init
git remote add origin https://your-remote-add/boot-tests.git

```

--------------------------------

### Install Python Development Libraries on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs the Python development libraries required by gem5 on Ubuntu. Ensure Python 3.6+ is installed.

```bash
sudo apt install python3-dev

```

--------------------------------

### Create and touch a new config file

Source: https://www.gem5.org/documentation/learning_gem5/part1/simple_config

Creates a new directory for tutorial configuration files and an empty Python script for gem5.

```bash
mkdir configs/tutorial/part1/
touch configs/tutorial/part1/simple.py

```

--------------------------------

### Create Configuration Directory and File

Source: https://www.gem5.org/documentation/learning_gem5/part1/cache_config

Creates the necessary directory and an empty Python file for the simulation configuration.

```bash
mkdir configs/tutorial/part1/
touch configs/tutorial/part1/components.py

```

--------------------------------

### Example InstId Field Values

Source: https://www.gem5.org/documentation/general_docs/cpu_models/minor_cpu

Provides a concrete example of the symbolic representation for InstId fields.

```text
- 0/10.12/5/6.7

```

--------------------------------

### HelloObject startup() and processEvent() Implementation

Source: https://www.gem5.org/documentation/learning_gem5/part2/events

Schedules the initial event in startup() and reschedules subsequent events in processEvent() based on latency and remaining times. The simulation ends when timesLeft reaches zero.

```cpp
void
HelloObject::startup()
{
    schedule(event, latency);
}

void
HelloObject::processEvent()
{
    timesLeft--;
    DPRINTF(HelloExample, "Hello world! Processing the event! %d left\n", timesLeft);

    if (timesLeft <= 0) {
        DPRINTF(HelloExample, "Done firing!\n");
    } else {
        schedule(event, curTick() + latency);
    }
}

```

--------------------------------

### Install Cross-Compilation Packages

Source: https://www.gem5.org/documentation/general_docs/fullsystem/building_android_m

Installs packages required for cross-compiling a 32-bit ARM kernel and the device tree.

```bash
sudo apt-get install gcc-arm-linux-gnueabihf device-tree-compiler

```

--------------------------------

### Install gdb-multiarch

Source: https://www.gem5.org/documentation/general_docs/debugging_and_testing/debugging/debugging_simulated_code

Installs the `gdb-multiarch` package for cross-architecture debugging. This is the recommended approach for remote debugging with gem5.

```bash
% sudo apt-get update -y
% sudo apt-get install -y gdb-multiarch

```

--------------------------------

### gem5 Help and Options

Source: https://www.gem5.org/documentation/general_docs/building

Display all available command-line options for gem5. This is useful for understanding and configuring simulation parameters.

```bash
Usage
=====
  gem5.opt [gem5 options] script.py [script options]

gem5 is copyrighted software; use the --copyright option for details.

Options
=======
--help, -h              show this help message and exit
--build-info, -B        Show build information
--copyright, -C         Show full copyright information
--readme, -R            Show the readme
--outdir=DIR, -d DIR    Set the output directory to DIR [Default: m5out]
--redirect-stdout, -r   Redirect stdout (& stderr, without -e) to file
--redirect-stderr, -e   Redirect stderr to file
--silent-redirect       Suppress printing a message when redirecting stdout or
                        stderr
--stdout-file=FILE      Filename for -r redirection [Default: simout.txt]
--stderr-file=FILE      Filename for -e redirection [Default: simerr.txt]
--listener-mode={on,off,auto}
                        Port (e.g., gdb) listener mode (auto: Enable if
                        running interactively) [Default: auto]
--allow-remote-connections
                        Port listeners will accept connections from anywhere
                        (0.0.0.0). Default is only localhost.
--interactive, -i       Invoke the interactive interpreter after running the
                        script
--pdb                   Invoke the python debugger before running the script
--path=PATH[:PATH], -p PATH[:PATH] Prepend PATH to the system path when invoking the
                        script
--quiet, -q             Reduce verbosity
--verbose, -v           Increase verbosity
-m mod                  run library module as a script (terminates option
                        list)
-c cmd                  program passed in as string (terminates option list)
-P                      Don't prepend the script directory to the system path.
                        Mimics Python 3's `-P` option.
-s                      IGNORED, only for compatibility with python. don'tadd
                        user site directory to sys.path; also PYTHONNOUSERSITE

Statistics Options
------------------
--stats-file=FILE       Sets the output file for statistics [Default:
                        stats.txt]
--stats-help            Display documentation for available stat visitors

Configuration Options
---------------------
--dump-config=FILE      Dump configuration output file [Default: config.ini]
--json-config=FILE      Create JSON output of the configuration [Default:
                        config.json]
--dot-config=FILE       Create DOT & pdf outputs of the configuration
                        [Default: config.dot]
--dot-dvfs-config=FILE  Create DOT & pdf outputs of the DVFS configuration
                        [Default: none]

Debugging Options
-----------------
--debug-break=TICK[,TICK]
                        Create breakpoint(s) at TICK(s) (kills process if no
                        debugger attached)
--debug-help            Print help on debug flags
--debug-flags=FLAG[,FLAG]
                        Sets the flags for debug output (-FLAG disables a
                        flag)
--debug-start=TICK      Start debug output at TICK
--debug-end=TICK        End debug output at TICK
--debug-file=FILE       Sets the output file for debug. Append '.gz' to the
                        name for it to be compressed automatically [Default:
                        cout]
--debug-activate=EXPR[,EXPR]
                        Activate EXPR sim objects
--debug-ignore=EXPR     Ignore EXPR sim objects
--remote-gdb-port=REMOTE_GDB_PORT
                        Remote gdb base port (set to 0 to disable listening)

Help Options
------------
--list-sim-objects      List all built-in SimObjects, their params and default
                        values

```

--------------------------------

### Install Flower for Celery Monitoring

Source: https://www.gem5.org/documentation/gem5art/main/faq

Install the Flower package using pip to monitor Celery tasks.

```bash
pip install flower

```

--------------------------------

### start_traffic Method

Source: https://www.gem5.org/documentation/general_docs/stdlib_api/gem5.components.processors.gups_generator_par.html

Starts the GUPS traffic generation. This method is a pass-through for GUPSGeneratorPAR as generation starts automatically.

```APIDOC
## def start_traffic() -> None

### Description
Starts the GUPS traffic generation. This method is a pass-through for GUPSGeneratorPAR as generation starts automatically.

### Method
This is a method of the GUPSGeneratorPAR class.
```

--------------------------------

### Full Hello World Script

Source: https://www.gem5.org/documentation/gem5-stdlib/hello-world-tutorial

A complete Python script to set up and run a 'Hello World' simulation using gem5 components.

```python
from gem5.components.boards.simple_board import SimpleBoard
from gem5.components.cachehierarchies.classic.no_cache import NoCache
from gem5.components.memory.single_channel import SingleChannelDDR3_1600
from gem5.components.processors.cpu_types import CPUTypes
from gem5.components.processors.simple_processor import SimpleProcessor
from gem5.isas import ISA
from gem5.resources.resource import obtain_resource
from gem5.simulate.simulator import Simulator

# Obtain the components.
cache_hierarchy = NoCache()
memory = SingleChannelDDR3_1600("1GiB")
processor = SimpleProcessor(cpu_type=CPUTypes.ATOMIC, num_cores=1, isa=ISA.X86)

# Add them to the board.
board = SimpleBoard(
    clk_freq="3GHz",
    processor=processor,
    memory=memory,
    cache_hierarchy=cache_hierarchy,
)

# Set the workload.
binary = obtain_resource("x86-hello64-static")
board.set_se_binary_workload(binary)

# Setup the Simulator and run the simulation.
simulator = Simulator(board=board)
simulator.run()

```

--------------------------------

### Install PARSEC and Dependencies

Source: https://www.gem5.org/documentation/gem5art/tutorials/parsec-tutorial

Installs necessary build tools and PARSEC benchmark suite within the disk image environment. This script updates package lists, installs essential development packages, and then proceeds to compile and set up PARSEC.

```bash
# install build-essential (gcc and g++ included)

#Compile PARSEC

cd /home/gem5/
su gem5
echo "12345" | sudo -S apt update

# Allowing services to restart while updating some
# libraries.
sudo apt install -y debconf-utils
sudo debconf-get-selections | grep restart-without-asking > libs.txt
sed -i 's/false/true/g' libs.txt
while read line; do echo $line | sudo debconf-set-selections; done < libs.txt
sudo rm libs.txt
##

# Installing packages needed to build PARSEC
sudo apt install -y build-essential
sudo apt install -y m4
sudo apt install -y git
sudo apt install -y python
sudo apt install -y python-dev
sudo apt install -y gettext
sudo apt install -y libx11-dev
sudo apt install -y libxext-dev
sudo apt install -y xorg-dev
sudo apt install -y unzip
sudo apt install -y texinfo
sudo apt install -y freeglut3-dev
##

# Building PARSEC

echo "12345" | sudo -S chown gem5 -R parsec-benchmark/
echo "12345" | sudo -S chgrp gem5 -R parsec-benchmark/
cd parsec-benchmark
./install.sh
./get-inputs
cd ..
echo "12345" | sudo -S chown gem5 -R parsec-benchmark/
echo "12345" | sudo -S chgrp gem5 -R parsec-benchmark/
##

```

--------------------------------

### Install gem5 Dependencies on Ubuntu 20.04

Source: https://www.gem5.org/documentation/general_docs/building

Installs required dependencies for gem5 on Ubuntu 20.04 using APT.

```bash
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \
    libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
    python3-dev python-is-python3 libboost-all-dev pkg-config gcc-10 g++-10 \
    python3-tk clang-format-18

```

--------------------------------

### Install gem5 Dependencies on Ubuntu 22.04

Source: https://www.gem5.org/documentation/general_docs/building

Installs required dependencies for gem5 on Ubuntu 22.04 using APT.

```bash
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev \
    libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
    python3-dev libboost-all-dev pkg-config python3-tk clang-format-15

```

--------------------------------

### Build and Run X86 Demo Board

Source: https://www.gem5.org/documentation/general_docs/stdlib_api/gem5.prebuilt.demo.x86_demo_board.html

This snippet shows the commands to build the gem5 executable and then run a configuration script using the X86DemoBoard. Ensure gem5 is built with the correct architecture and the configuration script is available.

```bash
scons build/X86/gem5.opt -j`nproc`
./build/X86/gem5.opt configs/example/gem5_library/x86-ubuntu-run.py

```

--------------------------------

### Install SCons on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs SCons, the build system used by gem5, on Ubuntu. SCons is a Python-based build tool.

```bash
sudo apt install scons

```

--------------------------------

### Create Configuration Directory and File

Source: https://www.gem5.org/documentation/learning_gem5/part1/simple_config

Creates the necessary directory and an empty Python configuration file for gem5.

```bash
mkdir configs/tutorial/part1/
touch configs/tutorial/part1/simple.py
```

--------------------------------

### Build m5term

Source: https://www.gem5.org/documentation/general_docs/fullsystem/m5term

Navigate to the util/term directory and build m5term using make. This includes compiling the C source file and installing the executable.

```bash
cd gem5/util/term
make
gcc  -o m5term term.c
make install
sudo install -o root -m 555 m5term /usr/local/bin
```

--------------------------------

### Install gem5 Dependencies on Ubuntu 24.04

Source: https://www.gem5.org/documentation/general_docs/building

Installs all required and optional dependencies for gem5 on Ubuntu 24.04 using APT.

```bash
sudo apt install build-essential scons python3-dev git pre-commit zlib1g zlib1g-dev \
    libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev \
    libboost-all-dev  libhdf5-serial-dev python3-pydot python3-venv python3-tk mypy \
    m4 libcapstone-dev libpng-dev libelf-dev pkg-config wget cmake doxygen clang-format

```

--------------------------------

### Initial Configuration with defconfig

Source: https://www.gem5.org/documentation/general_docs/kconfig_build_system

Use 'defconfig' to create an initial configuration in a specified build directory based on a provided configuration file. The exact path of the configuration is stored in the build directory.

```bash
scons defconfig gem5_build build_opts/ALL
```

--------------------------------

### Install RabbitMQ Server

Source: https://www.gem5.org/documentation/gem5art/main/tasks

Installs the RabbitMQ server, which is required as a message broker for Celery communication. This command is for Debian-based systems.

```bash
apt-get install rabbitmq-server
```

--------------------------------

### Apply Overlay Changes to init.gem5.rc

Source: https://www.gem5.org/documentation/general_docs/fullsystem/building_android_m

Shows the diff for changes made to the init.gem5.rc file, which configures system initialization.

```diff
  --- /kitkat_overlay/init.gem5.rc
  +++ /m_overlay/init.gem5.rc
@@ -1,21 +1,13 @@
  +
   on early-init
       mount debugfs debugfs /sys/kernel/debug
  
   on init
  -    export LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/vendor/lib/egl
  -
  -    # See storage config details at http://source.android.com/tech/storage/
  -    mkdir /mnt/media_rw/sdcard 0700 media_rw media_rw
  -    mkdir /storage/sdcard 0700 root root
  +    # Support legacy paths
  +    symlink /sdcard /mnt/sdcard
       chmod 0666 /dev/mali0
       chmod 0666 /dev/ion
  -
  -    export EXTERNAL_STORAGE /storage/sdcard
  -
  -    # Support legacy paths
  -    symlink /storage/sdcard /sdcard
  -    symlink /storage/sdcard /mnt/sdcard
  
   on fs
       mount_all /fstab.gem5
  @@ -60,7 +52,6 @@
       group root
       oneshot
  
  -# fusewrapped external sdcard daemon running as media_rw (1023)
  -service fuse_sdcard /system/bin/sdcard -u 1023 -g 1023 -d
  -/mnt/media_rw/sdcard /storage/sdcard
  +service fingerprintd /system/bin/fingerprintd
       class late_start
  -    disabled
  +    user system
```

--------------------------------

### Initialize a Blank Disk Image with gem5img.py

Source: https://www.gem5.org/documentation/general_docs/fullsystem/disks

Creates a new disk image formatted with ext2. This command may require sudo privileges. Always understand the script's functionality before execution.

```bash
> util/gem5img.py init ubuntu-14.04.img 4096

```

--------------------------------

### Install Autoconf Tools on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

This command installs the necessary autoconf tools, which may be required if the M4 macro processor is not found.

```bash
sudo apt-get install automake

```

--------------------------------

### Example Usage of Spatter Trace Parsing and Kernel Preparation

Source: https://www.gem5.org/documentation/general_docs/stdlib_api/gem5.components.processors.spatter_gen.spatter_kernel.html

Demonstrates how to use utility functions to parse a spatter trace, partition it for multiple cores, and create SpatterKernel objects for simulation.

```python
generator = SpatterGenerator(num_cores)

with open(trace_path, "r") as trace_file:
    kernels = json.load(trace_file)

for i, kernel in enumerate(kernels):
    delta, count, type, og_trace = parse_kernel(kernel)
    traces = partition_trace(og_trace, num_cores, 128)
    kernels = [SpatterKernel(
        kernel_id=i, kernel_delta=delta, kernel_count=count, kernel_type=type, kernel_trace=trace, index_size=4, base_index_addr=0, value_size=8, base_value_addr=0x400000000 )
    for trace in traces ]
    generator.add_kernel(kernels)
```

--------------------------------

### Install Boost Libraries on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs the Boost C++ libraries on Ubuntu. This is a necessary dependency for using the SystemC implementation of gem5.

```bash
sudo apt install libboost-all-dev

```

--------------------------------

### Install KVM Dependencies on Debian/Ubuntu

Source: https://www.gem5.org/documentation/general_docs/using_kvm

Install the necessary packages for KVM functionality with gem5. This includes QEMU, libvirt, and bridge utilities.

```bash
sudo apt-get install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils

```

--------------------------------

### Update and Install Dependencies

Source: https://www.gem5.org/documentation/general_docs/fullsystem/building_android_m

Installs necessary packages for Android development on Ubuntu 14.04 LTS. Ensure your system is up-to-date before running.

```bash
sudo apt-get update

sudo apt-get install openjdk-7-jdk git-core gnupg flex bison gperf build-essential zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache libgl1-mesa-dev libxml2-utils xsltproc unzip

```

--------------------------------

### Set Up SE Workload and Process

Source: https://www.gem5.org/documentation/learning_gem5/part1/simple_config

Initializes a workload for syscall emulation (SE) mode and configures a process with a command to be executed by the CPU.

```Python
binary = 'tests/test-progs/hello/bin/x86/linux/hello'

# for gem5 V21 and beyond
system.workload = SEWorkload.init_compatible(binary)

process = Process()
process.cmd = [binary]
system.cpu.workload = process
system.cpu.createThreads()

```

--------------------------------

### Install Build Essential on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs the essential build tools, including GCC, on Ubuntu. This is required for compiling C++ code for gem5.

```bash
sudo apt install build-essential

```

--------------------------------

### Example: Pull Ubuntu 20.04 Docker Image for gem5

Source: https://www.gem5.org/documentation/general_docs/building

Pulls the Docker image for Ubuntu 20.04 with all optional dependencies for gem5.

```bash
docker pull ghcr.io/gem5/ubuntu-20.04_all-dependencies:v23-0

```

--------------------------------

### Install gem5art Python Packages

Source: https://www.gem5.org/documentation/gem5art/tutorials/microbench-tutorial

Installs the necessary gem5art packages using pip. Ensure your virtual environment is activated before running this command.

```bash
pip install gem5art-artifact gem5art-run gem5art-tasks

```

--------------------------------

### Send Forward GetS to Owner

Source: https://www.gem5.org/documentation/learning_gem5/part3/directory

Forwards a GetS request to the owner of a block. Asserts exactly one owner. Uses `request_in` and `forward_out`.

```SLICC
action(sendFwdGetS, "fS", desc="Send forward getS to owner") {
    assert(getDirectoryEntry(address).Owner.count() == 1);
    peek(request_in, RequestMsg) {
        enqueue(forward_out, RequestMsg, 1) {
            out_msg.addr := address;
            out_msg.Type := CoherenceRequestType:GetS;
            out_msg.Requestor := in_msg.Requestor;
            out_msg.Destination := getDirectoryEntry(address).Owner;
            out_msg.MessageSize := MessageSizeType:Control;
        }
    }
}
```

--------------------------------

### Instantiate and Run a Custom Board Simulation

Source: https://www.gem5.org/documentation/gem5-stdlib/develop-stdlib-board

This snippet demonstrates how to instantiate the custom UniqueBoard, set a SE binary workload, and run the simulation using the gem5 Simulator.

```python
from unique_board import UniqueBoard

from gem5.resources.resource import obtain_resource
from gem5.simulate.simulator import Simulator

board = UniqueBoard(clk_freq="1.2GHz")

# As we are using the RISCV ISA, "riscv-hello" should work.
board.set_se_binary_workload(obtain_resource("riscv-hello"))

simulator = Simulator(board=board)
simulator.run()

```

--------------------------------

### Select Custom Routing Algorithm via Command Line

Source: https://www.gem5.org/documentation/general_docs/ruby/interconnection-network

Demonstrates how to select a custom routing algorithm (e.g., algorithm 2) from the command line when configuring the network simulation.

```bash
--routing-algorithm=2
```

--------------------------------

### Install Git on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs the Git version control system on Ubuntu. Git is used for managing the gem5 project's source code.

```bash
sudo apt install git

```

--------------------------------

### Install gem5 Dependencies on Ubuntu

Source: https://www.gem5.org/documentation/learning_gem5/part1/building

Installs all essential dependencies for building gem5 on Ubuntu systems. This includes build tools, version control, and libraries.

```bash
sudo apt install build-essential git m4 scons zlib1g zlib1g-dev libprotobuf-dev protobuf-compiler libprotoc-dev libgoogle-perftools-dev python-dev python

```

--------------------------------

### Install Commit-Message Hook and Amend Commit

Source: https://www.gem5.org/documentation/general_docs/common-errors

Install the commit-message hook from Gerrit to ensure a Change-Id is added to your commit messages. Then, amend your commit to include it.

```bash
n f=.git/hooks/commit-msg ; mkdir -p  ;  curl -Lo  https://gerrit-review.googlesource.com/tools/hooks/commit-msg ; chmod +x
git commit --amend --no-edit
```
Tokens:
Raw