gem5 Getting Started

gem5 is huge

suggest decide which architecture you want (eg X86) 
build only part you want

make sure have upto date 
  compiler (eg gcc version 10.2.1)
  python   (eg 3.7.3) 
  scons    (eg v4.5.2)
  m4       (eg 1.4.16)

make sure something like the following works

build/ALL/gem5.opt ssbse-challenge-examples/hello-custom-binary.py --isa X86 --binary ../hello64-static

hello-custom-binary.py avoid SSH network problems by using local only
--isa                  X86 which CPU type you are interested in
--binary               name of X86 executable
../hello64-static      small example executable binary compiled for X86

gem5 statistics goes into separate files (not stdout)

Building a shared library

E.g.

scons build/X86/libgem5_opt.so --no-colors --verbose

scons

parallel processing -j

If you have multiple cores, suggest using -j to speed up scons builds

verbose

By default with gem5 scons is fairly quiet.

To get gem5 scons to reflect command lines (like make V=1) use something like:

scons build/X86/gem5.opt --verbose

This will be very verbose.

See How to set scons to output full expanded command line? and manpage

no-colors

If saving output, but you dont want escape sequences in your record, add --no-colors to the scons command line.

Messing up scons

The directory build/*/gem5.build/scons_config/ contains .o files. Do not delete these.

After deleting these, scons gave totally confusing error messages. Such as:

Info: Using Python config: python3-config
Checking for C header file Python.h... (cached) yes
Checking Python version... no
Error: Can't find a working Python installation

and exited with status code 1 (There was nothing wrong with python or python3-config).

If you are lucky it may be possible to restore these .o files and get scons running again.

gcov scons

gcov is the GNU tool for measuring source code test coverage. Unlike linux perf, gcov requires the program to be compiled and linked with special flags/options to support it. When the instrumented version of the program is run, specialised files containing information about each program line actually run are written.
It does not seem that gem5 has already got support for gcov. It seems possible to add --gcov option to (the outer most) SConstruct.

Perhaps something like:

AddOption('--gcov', action='store_true',
          help='Enable support for the gcov coverage of gem5 tool')

    if GetOption('gcov'):
        env.Append(CCFLAGS=['-g', '-O0', '--coverage'], LINKFLAGS=['--coverage'])

Compiling and Linking for gcov

scons build/X86/gem5.debug --gcov --no-colors --verbose

will generate 1724 .do object files and 2098 .gcno The .gcno files "contain information to reconstruct the basic block graphs and assign source line numbers to blocks".

Generating gcov Data

When the gcov version of gem5 is run, on exit it will generate 1757 .gcda count data file. Eg

build/X86/gem5.debug gem5-ssbse-challenge-2023/ssbse-challenge-examples/hello-custom-binary.py --isa X86 --binary hello64-static

NB running the gcov version of gem5 again will update the .gcda files (rather than replace them).

Generating gcov output

In directory build/X86/

gcov `find -iname '*.gcda'`

will generate 1932 .gcov text output files in the current directory (gcov takes several minutes). However be wary that different gem5 directories contain files with the same name and hence gcov will generate overlapping output files of the same name.

Having thousands of files scattered over 129 different directories is bound to cause confusion.

Errors with gcov

Running gcov does not work.

Missing file name

gcov by itself effectively gives a command line syntax error and produces gcov help text.

file name . does not work

gcov .
.gcno:cannot open notes file
.gcda:cannot open data file, assuming not executed

gcov needs to be given an .gcda on its command line (see above).

version 'B02R', prefer '408R'

gcov produces a message like

gcov ./build/X86/arch/x86/decoder.gcda
./build/X86/arch/x86/decoder.gcno:version 'B02R', prefer '408R'
./build/X86/arch/x86/decoder.gcno:no functions found

Did you fail to set up $PATH the same as when gem5 was run?

gcov misc

To worry about.
gcov environment variables

GCOV_PREFIX
GCOV_PREFIX_STRIP

W.B.Langdon 7 August 2023 (last update 28 August 2023)