This repository contains tips and tricks about gem5. It is intended to gather and share useful hints about gem5, so that the learning process is accelerated.
If you decide to use gem5.TnT or parts of it, please cite this website https://github.com/tukl-msd/gem5.TnT.
- dep_install.sh: installs known dependencies for building gem5 and running the example scripts contained in this repository.
- get_essential_repos.sh: clones gem5 essential repositories for running the examples.
- get_extra_repos.sh: clones other gem5 related repositories.
- get_essential_fs.sh: downloads essential full system files for running the examples.
- get_extra_fs.sh: downloads full system files.
- get_doc.sh: downloads documentation and tutorials.
- get_benchmarks.sh: downloads benchmarks.
- build_gem5.sh: can be used for building gem5.
- ALPHA Boot Linux, Benchmarks scripts and information for the ALPHA.
- X86 Boot Linux, Boot Linux using KVM, PARSEC, MiBench scripts and information for x86.
- ARM Boot Linux, Android, Benchmarks scripts and information for arm.
- Basics here you will find some gem5 basics just to warmup. Remember, though, to take a look at gem5's website.
- mount-img.sh: convenience script for mounting disk images.
- create-img.sh: convenience script for creating disk images.
- copy-into-img.sh: convenience script for copying a folder into a disk image.
$ cd $HOME
$ git clone https://github.com/tukl-msd/gem5.TnT.git
$ cd gem5.TnTA suggestion on how to do that follows:
Install known dependencies (note that this one has to be run with sudo or as root):
$ sudo ./dep_install.shGet repositories:
$ ./get_essential_repos.shGet some full system simulation files:
$ ./get_essential_fs.shGet some benchmark suites:
$ ./get_benchmarks.shOptionally, download some documentation with:
$ ./get_doc.shThe default directory for downloads is $HOME/gem5_tnt. That means a new directory called gem5_tnt will be created in your home folder and populated with relevant files, documentation and repositories. In case you want to change the default paths edit the defaults.in file in your local repository before running the scripts.
A convenient script do_it_for_me.sh is provided.
$ ./do_it_for_me.shOne may want to copy files into a disk or from it, change configuration files, etc. A convenience script is provided to mount disk images quickly.
$ ./mount-img.sh <disk.img>Example of use:
$ ./mount-img.sh $HOME/gem5_tnt/full_system/arm/aarch-system-20180409/disks/linaro-minimal-aarch64.img
Salutations! You are using gem5.TnT!
file: $HOME/gem5_tnt/full_system/arm/aarch-system-20180409/disks/linaro-minimal-aarch64.img
start sector: 63
sector size: 512
loop device: /dev/loop0
offset: 32256
Mounted at /tmp/tmp.6zJKTZMqfV
Command to unmount: sudo umount /tmp/tmp.6zJKTZMqfV && sudo losetup --detach /dev/loop0In this example the mount point is /tmp/tmp.6zJKTZMqfV. The files there are the files used by gem5 during the simulation.
$ cd /tmp/tmp.6zJKTZMqfV
$ ls
bin boot dev etc home lib lost+found media mnt proc run sbin sys tmp usr varSwitch to superuser and search for /sbin/m5.
$ su
# grep "/sbin/m5" * -nrIil
usr/bin/auto-root-login
In this disk image the /sbin/m5 is used in usr/bin/auto-root-login. As root you shall be able to examine files, copy applications, etc.
# cat usr/bin/auto-root-login
#!/bin/sh
# Tony's modifications
# check if we're automatically starting a run script
/sbin/m5 readfile > /tmp/script
chmod 755 /tmp/script
if [ -s /tmp/script ]; then
exec /tmp/script
fi
exec /bin/login -f root
To exit superuser mode type exit.
# exit
Get out of the mount point, close any files you may have open, then unmount the disk image with the command suggested by mount-img.sh.
$ cd -
$ sudo umount /tmp/tmp.6zJKTZMqfV && sudo losetup --detach /dev/loop0 $ cd $HOME/gem5_tnt/gem5
$ scons --ignore-style -h$ python2.7 `which scons` build/<arch>/gem5.<mode> -j<num jobs>Example:
$ python2.7 `which scons` build/ARM/gem5.opt -j$(cat /proc/cpuinfo | grep processor | wc -l)$ sudo su
$ echo 1 > /proc/sys/vm/overcommit_memory$ build/X86/gem5.opt --help
$ build/X86/gem5.opt --debug-helpTry also the fast version for comparision:
$ build/X86/gem5.fast --help
$ build/X86/gem5.fast --debug-help$ cd $HOME/gem5_tnt/gem5
$ ls configs/example
$ ls configs/example/armSome scripts provide help.
$ build/X86/gem5.opt configs/example/fs.py --help
$ build/ARM/gem5.opt configs/example/arm/starter_fs.py --help
$ build/ARM/gem5.opt configs/example/se.py --helpSome scripts provide help for specific configurations.
$ build/X86/gem5.opt configs/example/fs.py --list-cpu-types
$ build/ARM/gem5.opt configs/example/se.py --list-mem-typesUsing KVM:
$ cd $HOME/gem5_tnt/gem5
$ scons --ignore-style -h | grep KVM
USE_KVM: Enable hardware virtualized (KVM) CPU models (yes|no)
$ echo "USE_KVM = 'yes'" >> build_opts/X86
$ cat build_opts/X86
$ rm -rf build/X86
$ scons --ignore-style build/X86/gem5.opt -j`nproc`Access to /dev/kvm is required.
$ groups
$ grep kvm /etc/group
$ sudo adduser $USER kvmRestart your computer for the permissions to take effect.
This may be necessary:
$ sudo su
# echo 1 > /proc/sys/kernel/perf_event_paranoid
# exit
$ cat /proc/sys/kernel/perf_event_paranoid
Still it may fail.
See also:
https://gem5-users.gem5.narkive.com/8DBihuUx/running-fs-py-with-x86kvmcpu-failed
https://github.com/darchr/gem5/tree/master
Build m5term.
$ cd $HOME/gem5_tnt/gem5
$ cd util/term
$ makeStart your gem5 simulation. The gem5 simulator generates a message with a port number for connection with m5term or telnet.
Example of use follows.
$ ./m5term localhost 3456Note: the port number may vary.
Commands to build the m5 for the x86 ISA follow.
$ cd $HOME/gem5_tnt/gem5
$ cd util/m5
$ make -f Makefile.x86See also:
In m5.c there is a table that associates functionalities provided by m5 with actual functions that implement them. Each entry in the table has a string which corresponds to the name of a functionality, a function that implements it and another string showing the usage.
The m5_mem is created using mmap() in m5_mmap.c. Now it may be a good time to read mmap's manpage.
$ man mmapThe value of the first argument addr is NULL. Then the kernel chooses the address at which the mapping is created.
The size used is 0x10000 (65 KiB).
Pages of this mapping may be read and written (PROT_READ | PROT_WRITE).
The MAP_SHARE flag makes updates to the mapping visible to other processes that map the same file or other object referred to by the file descriptor fd (in this case /dev/mem).
M5OP_ADDR is defined in Makefile.x86 (-DM5OP_ADDR=0xFFFF0000). The combination of address and size generates the range 0xFFFF0000-0xFFFFFFFF.
M5OP_PIC can also be defined there (depending on the target). It indicates that Position Independent Code must be generated by using the code generation option -fPIC. Note that the default target is in Makefile.x86 is m5, but there are others e.g. m5op_x86.opic. The code generation option -fPIC is useful for creating code that can be dynamically linked, e.g. object files that compose dynamic libraries (.so).
Both M5OP_ADDR and M5OP_PIC affect how the macro TWO_BYTE_OP(name, number) is defined in m5op_x86.S. Such macro is used to define m5 operations. The respective numbers can be found in m5ops.h.
Example:
/* Use the memory mapped m5op interface */
#define TWO_BYTE_OP(name, number) \
.globl name; \
.func name; \
name: \
mov m5_mem, %r11; \
mov $number, %rax; \
shl $8, %rax; \
mov 0(%r11, %rax, 1), %rax; \
ret; \
.endfunc;
.global makes the symbol (name of a function) visible to ld (the linker)
TWO_BYTE_OP(m5_dump_stats, M5OP_DUMP_STATS)
TWO_BYTE_OP(m5_checkpoint, M5OP_CHECKPOINT)
The M5 binary has to be compiled for the guest machine (the one being simulated) and copied to the disk image. Usually it is found in /sbin/m5.
After booting the guest system, in a terminal:
#/sbin/m5 -h
usage: /sbin/m5 exit [delay]
/sbin/m5 fail <code> [delay]
/sbin/m5 resetstats [delay [period]]
/sbin/m5 dumpstats [delay [period]]
/sbin/m5 dumpresetstats [delay [period]]
/sbin/m5 readfile
/sbin/m5 writefile <filename> [host filename]
/sbin/m5 execfile
/sbin/m5 checkpoint [delay [period]]
/sbin/m5 addsymbol <address> <symbol>
/sbin/m5 loadsymbol
/sbin/m5 initparam [key] // key must be shorter than 16 chars
/sbin/m5 sw99param
/sbin/m5 pin <cpu> <program> [args ...]
All times in nanoseconds!
Calling /sbin/m5 dumpstats appends new simulation statistics to the output file stats.txt that can be found in the output folder of the simuation (default output folder is m5out).
---------- Begin Simulation Statistics ----------
...
---------- End Simulation Statistics ----------
Applications can also be linked to a library providing the m5 features.
Emulation functions that are generic enough that they don't need to be recompiled for different emulated OS's are defined in syscall_emul.cc. See also syscall_emul.hh.
The class SyscallDesc provides the wrapper interface for the system call implementations.
Note the tables with syscalls for x86 in src/arch/x86/linux/process.cc. There you can check if the syscalls needed by an application are implemented.
static SyscallDesc syscallDescs64[] {
/* 0 */ SyscallDesc("read", readFunc),
/* 1 */ SyscallDesc("write", writeFunc),
/* 2 */ SyscallDesc("open", openFunc<X86Linux64>),
/* 3 */ SyscallDesc("close", closeFunc),
...
/* 57 */ SyscallDesc("fork", unimplementedFunc),
...
}
static SyscallDesc syscallDescs32[] = {
/* 0 */ SyscallDesc("restart_syscall", unimplementedFunc),
/* 1 */ SyscallDesc("exit", exitFunc),
/* 2 */ SyscallDesc("fork", unimplementedFunc),
/* 3 */ SyscallDesc("read", readFunc),
...
}
Also in src/arch/x86/linux/process.cc you can find the implementation of uname that is a system call (a function provided by the kernel) to get name and information about the kernel, for example the kernel version. See also uname(2).
$ man 2 uname
In src/arch/riscv/linux/process.cc you can find information for RISC-V, in src/arch/arm/linux/process.cc you can find information for ARM, and so on.
Here some links you may consider useful. Many thanks to the respective authors for throwing some light on this.
http://www.gem5.org/Special:AllPages
When to use full system FS vs syscall emulation SE with userland programs in gem5?
How to solve “FATAL: kernel too old” when running gem5 in syscall emulation SE mode?
https://gem5-users.gem5.narkive.com/
The Ultimate Computer
Stardate: 4729.4
...
KIRK: I'm curious, Doctor. Why is it called M-5 and not M-1?
DAYSTROM: Well, you see, the multitronic units one through four were not entirely successful. This one is. M-5 is ready to take control of the ship.
...
MCCOY: Jim, he's on the edge of a nervous breakdown, if not insanity.
KIRK: The M-5 must be destroyed.
...
SPOCK: The force field is gone, Captain. M-5 is neutralised.
SCOTT: System's coming back.
...
gem5.TnT and its parts are released under the BSD 3-Clause License. This gives the users and developers the flexibility to employ, develop and re-distribute the source code with minimal obligations. We only ask users to cite https://github.com/tukl-msd/gem5.TnT.
You may use the software subject to the license terms below provided that you ensure that this notice is replicated unmodified and in its entirety in all distributions of the software, modified or unmodified, in source code or in binary form.
Copyright (c) TU Kaiserslautern All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
Neither the name of the copyright holders nor the names of its
contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
By cloning the gem5.TnT repository or downloading its contents or copying gem5.TnT or copying portions of gem5.TnT, you acknowledge that you have read, understood and accepted to use gem5.TnT under the terms of license detailed above.