The gem5.tnt from x-tinkerer

gem5 Tips & Tricks

Tips and tricks to make your life easier when dealing with gem5

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.

Using gem5.TnT

Clone the repository and change to its directory:

$ cd $HOME
$ git clone https://github.com/tukl-msd/gem5.TnT.git
$ cd gem5.TnT

Run the scripts.

A 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.sh

Get repositories:

$ ./get_essential_repos.sh

Get some full system simulation files:

$ ./get_essential_fs.sh

Get some benchmark suites:

$ ./get_benchmarks.sh

Download documentation

Optionally, download some documentation with:

$ ./get_doc.sh

The 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.sh

Mounting Disk Images

One 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/loop0

In 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  var

Switch 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

Quick Hints

GEM5 Scons Build Options:

$ cd $HOME/gem5_tnt/gem5
$ scons --ignore-style -h

Default python version is not python2.7:

$ 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)

Memory allocation error on Linux

$ sudo su
$ echo 1 > /proc/sys/vm/overcommit_memory

GEM5 Help

$ build/X86/gem5.opt --help
$ build/X86/gem5.opt --debug-help

Try also the fast version for comparision:

$ build/X86/gem5.fast --help
$ build/X86/gem5.fast --debug-help

Configurations scripts provided as examples

$ cd $HOME/gem5_tnt/gem5
$ ls configs/example
$ ls configs/example/arm

Some 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 --help

Some 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-types

Using 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 kvm

Restart 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.

M5 Term

Build m5term.

$ cd $HOME/gem5_tnt/gem5
$ cd util/term
$ make

Start 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 3456

Note: the port number may vary.

The M5 Binary

Commands to build the m5 for the x86 ISA follow.

$ cd $HOME/gem5_tnt/gem5
$ cd util/m5
$ make -f Makefile.x86

Using the M5 Binary

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.

Syscall Emulation SE

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.

More Resources, Useful Links

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

Learning gem5

Tutorials gem5 wiki

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?

gem5 vs QEMU

https://gem5-users.gem5.narkive.com/

setting-up-gem5-full-system

More Resources, Useless Links

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.
...

Source

Licensing:

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.

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.

Download:

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.

x-tinkerer / gem5.tnt Goto Github PK

gem5.tnt's Introduction