The perfect emulation setup to study and modify the Linux kernel, kernel modules, QEMU and gem5. Highly automated. Thoroughly documented. GDB step debug and KGDB just work. Powered by Buildroot. "Tested" in Ubuntu 18.04 host, x86 and ARM guests with kernel v4.19.
Type Name Latest commit message Commit time
Failed to load latest commit information.
baremetal multicore: remove references to PCSI Nov 26, 2018
buildroot_config investigate squashfs to overcome BR2_TARGET_ROOTFS_EXT2_SIZE but fail Sep 15, 2018
buildroot_packages build-buildroot: add the --no-overlay option Nov 6, 2018
crosstool_ng_config kgdb is perfect Nov 2, 2018
hello_host_kernel_module kgdb is perfect Nov 2, 2018
include get rid of lkmc package, move userland and kernel-modules to top Oct 25, 2018
kernel_modules lvimrc: move to kernel_modules directory Nov 29, 2018
linux_config gem5 display: a bit more info on dp650 Dec 4, 2018
patches get rid of unused patches/buildroot Nov 15, 2018
rootfs_overlay rootfs_overlay: qemu_edu: fix kernel module name Nov 4, 2018
submodules gem5: update to a5bc2291391b0497fdc60fdc960e07bcecebfb8f Nov 23, 2018
userland userland: support arch specific examples Nov 20, 2018
.dockerignore docker: split minimum setup to separate script Nov 17, 2018
.gitignore host kernel module works Oct 31, 2018
.gitmodules gem5: update to 7bfb7f3a43f382eb49853f47b140bfd6caad0fb8 Sep 23, 2018
.travis.yml download-dependencies: merge into ./build --download-dependencies Nov 10, 2018
CONTRIBUTING.adoc Move contributing to readme May 5, 2018
Dockerfile docker: split minimum setup to separate script Nov 17, 2018
LICENSE.txt license Jun 7, 2017
README.adoc parsec: fix package name on README with underscore Dec 10, 2018
arm gdb: create some automated tests with pytest Nov 9, 2018
bench-all getting started: hide the initial build under ./build Oct 14, 2018
bench-boot better build setups for testing and release Nov 3, 2018
bench-cmd some small fixes Sep 14, 2018
bisect-linux-boot-gem5 move all builds to components Oct 23, 2018
bisect-qemu-linux-boot lkmc v2-rc Sep 14, 2018
bst-vs-heap lkmc v2-rc Sep 14, 2018
build prebuilt: automatically pick up qemu from PATH if not built like qemu… Nov 22, 2018
build-baremetal baremetal: only rebuild required files based on mtime Nov 22, 2018
build-bench-boot better build setups for testing and release Nov 3, 2018
build-buildroot common: add --qemu option to override configs Nov 13, 2018
build-crosstool-ng build: make baremetal parts more flexible and powerful Nov 9, 2018
build-doc readme: fix all broken asciidoctor links. Apr 7, 2018
build-docker docker: move to component Oct 24, 2018
build-gem5 gem5: update to a5bc2291391b0497fdc60fdc960e07bcecebfb8f Nov 23, 2018
build-linux kernel: add section about /proc/version Dec 5, 2018
build-m5 manually encode newlines on all printed commands Nov 4, 2018
build-modules bring a minimal buildroot kernel modules example to life Nov 5, 2018
build-qemu manually encode newlines on all printed commands Nov 4, 2018
build-test build: make baremetal parts more flexible and powerful Nov 9, 2018
build-test-gdb build: make baremetal parts more flexible and powerful Nov 9, 2018
build-userland userland: support arch specific examples Nov 20, 2018
buildroot_override lkmc v2-rc Sep 14, 2018
busybox_config_fragment Add a shortcute for / Mar 14, 2018
common.c Factor common userland and baremetal C functions Nov 15, 2018
common.h Factor common userland and baremetal C functions Nov 15, 2018 kernel: add section about /proc/version Dec 5, 2018
config.example lkmc v2-rc Sep 14, 2018
copy-overlay copy-overlay. ./build broken btw :-) Oct 25, 2018
eeval lkmc v2-rc Sep 14, 2018
gem5-bench-cache lkmc v2-rc Sep 14, 2018
gem5-bench-dhrystone gem5: update to 7bfb7f3a43f382eb49853f47b140bfd6caad0fb8 Sep 23, 2018
gem5-shell manually encode newlines on all printed commands Nov 4, 2018
gem5-stat lkmc v2-rc Sep 14, 2018
getvar gem5: update to 7bfb7f3a43f382eb49853f47b140bfd6caad0fb8 Sep 23, 2018
qemu-monitor qemu-monitor: migrate to Python! Nov 10, 2018
qemu-rr gem5: update to 7bfb7f3a43f382eb49853f47b140bfd6caad0fb8 Sep 23, 2018
qemu-trace2txt manually encode newlines on all printed commands Nov 4, 2018
release better build setups for testing and release Nov 3, 2018
release-download-latest relase: make github operations perfect Sep 17, 2018
release-upload relase: make github operations perfect Sep 17, 2018
release-zip getting started: hide the initial build under ./build Oct 14, 2018
requirements.txt gdb: create some automated tests with pytest Nov 9, 2018
rootfs-post-build-script getting started: explain 9p module rebuild Oct 14, 2018
run gem5: use --generate-dtb by default Dec 4, 2018
run-docker the docker setup is perfect Nov 11, 2018
run-gdb gem5: fix arm multicore with system.auto_reset_addr = True Nov 26, 2018
run-gdb-user gdb userland and gdbserver are perfect Nov 3, 2018
run-gdbserver gdb userland and gdbserver are perfect Nov 3, 2018
run-toolchain gem5: fix arm multicore with system.auto_reset_addr = True Nov 26, 2018
setup docker: split minimum setup to separate script Nov 17, 2018
test build: make baremetal parts more flexible and powerful Nov 9, 2018
test-gdb gdb: stub for testing userland Nov 15, 2018
test-gem5-graphics gem5 display: a bit more info on dp650 Dec 4, 2018
test-modules test-kernel-modules: rename to test-modules to match build-modules Nov 9, 2018
tmu tmu: fix window switch for build problem Apr 22, 2018
trace-boot trace: improve a bit, fix bugs Nov 23, 2018
trace2line common: add --qemu option to override configs Nov 13, 2018 lkmc v2-rc Sep 14, 2018
update-buildroot-kernel-configs Build the Linux kernel independently from Buildroot Oct 12, 2018
user_table Add a non-root user user0 password "a" Aug 6, 2017
vnc docker: crate docker host setup Apr 8, 2018
x11.png x11 screenshot and link to insmod C Sep 26, 2017


Linux Kernel Module Cheat

The perfect emulation setup to study and modify the Linux kernel, kernel modules, QEMU and gem5. Highly automated. Thoroughly documented. GDB step debug and KGDB just work. Powered by Buildroot. "Tested" in Ubuntu 18.04 host, x86 and ARM guests with kernel v4.19.

1. Getting started

Each child section describes a possible different setup for this repo.

If you don’t know which one to go for, start with QEMU Buildroot setup getting started.

1.1. QEMU Buildroot setup

1.1.1. QEMU Buildroot setup getting started

This setup has been mostly tested on Ubuntu. For other host operating systems see: Supported hosts.

Reserve 12Gb of disk and run:

git clone
cd linux-kernel-module-cheat
./build --download-dependencies qemu-buildroot

You don’t need to clone recursively even though we have .git submodules: download-dependencies fetches just the submodules that you need for this build to save time.

If something goes wrong, see: Common build issues and use our issue tracker:

The initial build will take a while (30 minutes to 2 hours) to clone and build, see Benchmark builds for more details.

If you don’t want to wait, you could also try the following faster but much more limited methods:

but you will soon find that they are simply not enough if you anywhere near serious about systems programming.

After ./run, QEMU opens up and you can start playing with the kernel modules inside the simulated system:

insmod /hello.ko
insmod /hello2.ko
rmmod hello
rmmod hello2

This should print to the screen:

hello init
hello2 init
hello cleanup
hello2 cleanup

which are printk messages from init and cleanup methods of those modules.


Quit QEMU with:

Ctrl-A X

All available modules can be found in the kernel_modules directory.

It is super easy to build for different CPU architectures, just use the --arch option:

./build --arch aarch64 --download-dependencies qemu-buildroot
./run --arch aarch64

To avoid typing --arch aarch64 many times, you set the default arch as explained at: Default command line arguments

See also: CPU architectures.

I now urge you to read the following sections which contain widely applicable information:

Once you use GDB step debug and tmux, your terminal will look a bit like this:

[    1.451857] input: AT Translated Set 2 keyboard as /devices/platform/i8042/s1│loading @0xffffffffc0000000: ../kernel_modules-1.0//timer.ko
[    1.454310] ledtrig-cpu: registered to indicate activity on CPUs             │(gdb) b lkmc_timer_callback
[    1.455621] usbcore: registered new interface driver usbhid                  │Breakpoint 1 at 0xffffffffc0000000: file /home/ciro/bak/git/linux-kernel-module
[    1.455811] usbhid: USB HID core driver                                      │-cheat/out/x86_64/buildroot/build/kernel_modules-1.0/./timer.c, line 28.
[    1.462044] NET: Registered protocol family 10                               │(gdb) c
[    1.467911] Segment Routing with IPv6                                        │Continuing.
[    1.468407] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver              │
[    1.470859] NET: Registered protocol family 17                               │Breakpoint 1, lkmc_timer_callback (data=0xffffffffc0002000 <mytimer>)
[    1.472017] 9pnet: Installing 9P2000 support                                 │    at /linux-kernel-module-cheat//out/x86_64/buildroot/build/
[    1.475461] sched_clock: Marking stable (1473574872, 0)->(1554017593, -80442)│kernel_modules-1.0/./timer.c:28
[    1.479419] ALSA device list:                                                │28      {
[    1.479567]   No soundcards found.                                           │(gdb) c
[    1.619187] ata2.00: ATAPI: QEMU DVD-ROM, 2.5+, max UDMA/100                 │Continuing.
[    1.622954] ata2.00: configured for MWDMA2                                   │
[    1.644048] scsi 1:0:0:0: CD-ROM            QEMU     QEMU DVD-ROM     2.5+ P5│Breakpoint 1, lkmc_timer_callback (data=0xffffffffc0002000 <mytimer>)
[    1.741966] tsc: Refined TSC clocksource calibration: 2904.010 MHz           │    at /linux-kernel-module-cheat//out/x86_64/buildroot/build/
[    1.742796] clocksource: tsc: mask: 0xffffffffffffffff max_cycles: 0x29dc0f4s│kernel_modules-1.0/./timer.c:28
[    1.743648] clocksource: Switched to clocksource tsc                         │28      {
[    2.072945] input: ImExPS/2 Generic Explorer Mouse as /devices/platform/i8043│(gdb) bt
[    2.078641] EXT4-fs (vda): couldn't mount as ext3 due to feature incompatibis│#0  lkmc_timer_callback (data=0xffffffffc0002000 <mytimer>)
[    2.080350] EXT4-fs (vda): mounting ext2 file system using the ext4 subsystem│    at /linux-kernel-module-cheat//out/x86_64/buildroot/build/
[    2.088978] EXT4-fs (vda): mounted filesystem without journal. Opts: (null)  │kernel_modules-1.0/./timer.c:28
[    2.089872] VFS: Mounted root (ext2 filesystem) readonly on device 254:0.    │#1  0xffffffff810ab494 in call_timer_fn (timer=0xffffffffc0002000 <mytimer>,
[    2.097168] devtmpfs: mounted                                                │    fn=0xffffffffc0000000 <lkmc_timer_callback>) at kernel/time/timer.c:1326
[    2.126472] Freeing unused kernel memory: 1264K                              │#2  0xffffffff810ab71f in expire_timers (head=<optimized out>,
[    2.126706] Write protecting the kernel read-only data: 16384k               │    base=<optimized out>) at kernel/time/timer.c:1363
[    2.129388] Freeing unused kernel memory: 2024K                              │#3  __run_timers (base=<optimized out>) at kernel/time/timer.c:1666
[    2.139370] Freeing unused kernel memory: 1284K                              │#4  run_timer_softirq (h=<optimized out>) at kernel/time/timer.c:1692
[    2.246231] EXT4-fs (vda): warning: mounting unchecked fs, running e2fsck isd│#5  0xffffffff81a000cc in __do_softirq () at kernel/softirq.c:285
[    2.259574] EXT4-fs (vda): re-mounted. Opts: block_validity,barrier,user_xatr│#6  0xffffffff810577cc in invoke_softirq () at kernel/softirq.c:365
hello S98                                                                       │#7  irq_exit () at kernel/softirq.c:405
                                                                                │#8  0xffffffff818021ba in exiting_irq () at ./arch/x86/include/asm/apic.h:541
Apr 15 23:59:23 login[49]: root login on 'console'                              │#9  smp_apic_timer_interrupt (regs=<optimized out>)
hello /root/.profile                                                            │    at arch/x86/kernel/apic/apic.c:1052
# insmod /timer.ko                                                              │#10 0xffffffff8180190f in apic_timer_interrupt ()
[    6.791945] timer: loading out-of-tree module taints kernel.                 │    at arch/x86/entry/entry_64.S:857
# [    7.821621] 4294894248                                                     │#11 0xffffffff82003df8 in init_thread_union ()
[    8.851385] 4294894504                                                       │#12 0x0000000000000000 in ?? ()

1.1.2. How to hack stuff

Besides a seamless initial build, this project also aims to make it effortless to modify and rebuild several major components of the system, to serve as an awesome development setup. Your first Linux kernel hack

Let’s hack up the Linux kernel entry point, which is an easy place to start.

Open the file:

vim submodules/linux/init/main.c

and find the start_kernel function, then add there a:


Then rebuild the Linux kernel, quit QEMU and reboot the modified kernel:


and, surely enough, your message has appeared at the beginning of the boot:

<6>[    0.000000] I'VE HACKED THE LINUX KERNEL!!!

So you are now officially a Linux kernel hacker, way to go!

We could have used just build to rebuild the kernel as in the initial build instead of build-linux, but building just the required individual components is preferred during development:

  • saves a few seconds from parsing Make scripts and reading timestamps

  • makes it easier to understand what is being done in more detail

  • allows passing more specific options to customize the build

The build script is just a lightweight wrapper that calls the smaller build scripts, and you can see what ./build does with:

./build --dry-run Your first kernel module hack

Edit kernel_modules/hello.c to contain:

pr_info("hello init hacked\n");

and rebuild with:


Now there are two way to test it out, the fast way, and the safe way.

The fast way is, without quitting or rebooting QEMU, just directly re-insert the module with:

insmod /mnt/9p/out_rootfs_overlay/hello.ko

and the new pr_info message should now show on the terminal at the end of the boot.

This works because we have a 9P mount there setup by default, which makes a host directory available on the guest.

The fast method is slightly risky because your kernel module might have corrupted the kernel memory, which could affect future runs.

Such failures are however unlikely, and you should be fine if you don’t see anything weird happening.

The safe way, is to fist quit QEMU, rebuild the modules, put them in the root filesystem, and then reboot:

./run --eval-after 'insmod /hello.ko'

./build-buildroot is required after ./build-modules because it generates the root filesystem with the modules that we compiled at ./build-modules.

You can see that ./build does that as well, by running:

./build --dry-run

--eval-after is optional: you could just type insmod /hello.ko in the terminal, but this makes it run automatically at the end of boot, and then drops you into a shell.

If the guest and host are the same arch, typically x86_64, you can speed up boot further with KVM:

./run --kvm

All of this put together makes the safe procedure acceptably fast for regular development as well. Your first QEMU hack

Not satisfied with mere software? OK then, let’s hack up the QEMU x86 CPU identification:

vim submodules/qemu/target/i386/cpu.c

and modify:

.model_id = "QEMU Virtual CPU version " QEMU_HW_VERSION,

to contain:

.model_id = "QEMU Virtual CPU version HACKED " QEMU_HW_VERSION,

then as usual rebuild and re-run:

./run --eval-after 'grep "model name" /proc/cpuinfo'

and once again, there is your message: QEMU communicated it to the Linux kernel, which printed it out.

You have now gone from newb to hardware hacker in a mere 15 minutes, your rate of progress is truly astounding!!!

Seriously though, if you want to be a real hardware hacker, it just can’t be done with open source tools as of 2018. The root obstacle is that:

The only thing you can do with open source is purely functional designs with Verilator, but you will never know if it can be actually produced and how efficient it can be.

If you really want to develop semiconductors, your only choice is to join an university or a semiconductor company that has the EDA licenses.

1.1.3. About the QEMU Buildroot setup

This is our reference setup, and the best supported one, use it unless you have good reason not to.

It was historically the first one we did, and all sections have been tested with this setup unless explicitly noted.

Read the following sections for further introductory material:

1.2. gem5 Buildroot setup

1.2.1. About the gem5 Buildroot setup

This setup is like the QEMU Buildroot setup, but it uses gem5 instead of QEMU as a system simulator.

QEMU tries to run as fast as possible and give correct results at the end, but it does not tell us how many CPU cycles it takes to do something, just the number of instructions it ran.

The number of instructions executed is a very poor estimator of performance because in modern computers, a lot of time is spent waiting for memory requests rather than the instructions themselves.

This kind of simulation is known as functional simulation.

gem5 on the other hand, can simulate the system in more detail than QEMU, including:

  • simplified CPU pipeline

  • caches

  • DRAM timing

and can therefore be used to estimate system performance, see: gem5 run benchmark for an example.

The downside of gem5 much slower than QEMU because of the greater simulation detail.

See gem5 vs QEMU for a more thorough comparison.

1.2.2. gem5 Buildroot setup getting started

For the most part, if you just add the --gem5 option or *-gem5 suffix to all commands and everything should magically work.

If you haven’t built Buildroot yet for QEMU Buildroot setup, you can build from the beginning with:

./build --download-dependencies gem5-buildroot
./run --gem5

If you have already built previously, don’t be afraid: gem5 and QEMU use almost the same root filesystem and kernel, so ./build will be fast.

Remember that the gem5 boot is considerably slower than QEMU since the simulation is more detailed.

To get a terminal, either open a new shell and run:


You can quit the shell without killing gem5 by typing tilde followed by a period:


If you are inside tmux, which I highly recommend, you can both run gem5 stdout and open the guest terminal on a split window with:

./run --gem5 --tmux

See also: tmux gem5.

At the end of boot, it might not be very clear that you have the shell since some printk messages may appear in front of the prompt like this:

# <6>[    1.215329] clocksource: tsc: mask: 0xffffffffffffffff max_cycles: 0x1cd486fa865, max_idle_ns: 440795259574 ns
<6>[    1.215351] clocksource: Switched to clocksource tsc

but if you look closely, the PS1 prompt marker # is there already, just hit enter and a clear prompt line will appear.

If you forgot to open the shell and gem5 exit, you can inspect the terminal output post-mortem at:

less "$(./getvar --gem5 m5out_dir)/system.pc.com_1.device"

More gem5 information is present at: gem5

Good next steps are:

1.3. Docker host setup

This repository has been tested inside clean Docker containers.

This is a good option if you are on a Linux host, but the native setup failed due to your weird host distribution, and you have better things to do with your life than to debug it. See also: Supported hosts.

For example, to do a QEMU Buildroot setup inside Docker, run:

sudo apt-get install docker
./run-docker create && \
./run-docker sh -- ./build --download-dependencies qemu-buildroot
./run-docker sh

You are now left inside a shell in the Docker! From there, just run as usual:


The host git top level directory is mounted inside the guest with a Docker volume, which means for example that you can use your host’s GUI text editor directly on the files. Just don’t forget that if you nuke that directory on the guest, then it gets nuked on the host as well!

Command breakdown:

  • ./run-docker create: create the image and container.

    Needed only the very first time you use Docker, or if you run ./run-docker DESTROY to restart for scratch, or save some disk space.

    The image and container name is lkmc. The container shows under:

    docker ps -a

    and the image shows under:

    docker images
  • ./run-docker sh: open a shell on the container.

    If it has not been started previously, start it. This can also be done explicitly with:

    ./run-docker start

    Quit the shell as usual with Ctrl-D

    This can be called multiple times from different host terminals to open multiple shells.

  • ./run-docker stop: stop the container.

    This might save a bit of CPU and RAM once you stop working on this project, but it should not be a lot.

  • ./run-docker DESTROY: delete the container and image.

    This doesn’t really clean the build, since we mount the guest’s working directory on the host git top-level, so you basically just got rid of the apt-get installs.

    To actually delete the Docker build, run on host:

    # sudo rm -rf out.docker

To use GDB step debug from inside Docker, you need a second shell inside the container. You can either do that from another shell with:

./run-docker sh

or even better, by starting a tmux session inside the container. We install tmux by default in the container.

You can also start a second shell and run a command in it at the same time with:

./run-docker sh -- ./run-gdb start_kernel

To use QEMU graphic mode from Docker, run:

./run --graphic --vnc

and then on host:

sudo apt-get install vinagre

TODO make files created inside Docker be owned by the current user in host instead of root:

1.4. Prebuilt Buildroot setup

1.4.1. About the prebuilt Buildroot setup

This setup uses prebuilt binaries of the QEMU Buildroot setup that we upload to GitHub from time to time.

We don’t currently provide a full prebuilt because it would be too big to host freely, notably because of the cross toolchain.

Our prebuilts currently include:

  • Linux kernel

  • root filesystem

For more details, see our our release procedure.

Advantage of this setup: saves time and disk space on the initial install, which is expensive in largely due to building the toolchain.

The limitations are severe however:

  • can’t GDB step debug the kernel, since the source and cross toolchain with GDB are not available. Buildroot cannot easily use a host toolchain: Buildroot use prebuilt host toolchain.

    Maybe we could work around this by just downloading the kernel source somehow, and using a host prebuilt GDB, but we felt that it would be too messy and unreliable.

  • you won’t get the latest version of this repository. Our Travis attempt to automate builds failed, and storing a release for every commit would likely make GitHub mad at us anyways.

  • gem5 is not currently supported. The major blocking point is how to avoid distributing the kernel images twice: once for gem5 which uses vmlinux, and once for QEMU which uses arch/* images, see also: vmlinux vs bzImage vs zImage vs Image.

This setup might be good enough for those developing simulators, as that requires less image modification. But once again, if you are serious about this, why not just let your computer build the full featured setup while you take a coffee or a nap? :-)

1.4.2. Prebuilt Buildroot setup getting started

Checkout to the latest tag and use the Ubuntu packaged QEMU:

sudo apt-get install qemu-system-x86
git clone
cd linux-kernel-module-cheat
git checkout "$(git rev-list --tags --max-count=1)"
unzip lkmc-*.zip
./run --prebuilt

You have to checkout to the latest tag to ensure that the scripts match the release format:

Be saner and use our custom built QEMU instead:

git submodule update --init --recursive "$(./getvar qemu_src_dir)"

This also allows you to modify QEMU if you’re into that sort of thing.

To build the kernel modules as in Your first kernel module hack do:

./build-linux -- modules_prepare

modules_prepare does the minimal build procedure required on the kernel for us to be able to compile the kernel modules, and is way faster than doing a full kernel build. A full kernel build would also work however.

This command automatically falls back to the Ubuntu packaged GCC since you don’t have the Buildroot toolchain.

To modify the Linux kernel, build and use it as usual:


1.5. Host kernel module setup


This method runs the kernel modules directly on your host computer without a VM, and saves you the compilation time and disk usage of the virtual machine method.

It has however severe limitations:

  • can’t control which kernel version and build options to use. So some of the modules will likely not compile because of kernel API changes, since the Linux kernel does not have a stable kernel module API.

  • bugs can easily break you system. E.g.:

    • segfaults can trivially lead to a kernel crash, and require a reboot

    • your disk could get erased. Yes, this can also happen with sudo from userland. But you should not use sudo when developing newbie programs. And for the kernel you don’t have the choice not to use sudo.

    • even more subtle system corruption such as not being able to rmmod

  • can’t control which hardware is used, notably the CPU architecture

  • can’t step debug it with GDB easily. The alternatives are JTAG or KGDB, but those are less reliable, and require extra hardware.

Still interested?

./build-modules --host

Compilation will likely fail for some modules because of kernel or toolchain differences that we can’t control on the host.

The best solution is to compile just your modules with:

./build-modules --host -- hello hello2

which is equivalent to:

./build-modules --host -- packages/kernel/modules/hello.c packages/kernel/modules/hello2.c

Or just remove the .c extension from the failing files and try again:

cd "$(./getvar kernel_modules_src_dir)"
mv broken.c broken.c~

Once you manage to compile, and have come to terms with the fact that this may blow up your host, try it out with:

cd "$(./getvar kernel_modules_build_host_subdir)"
sudo insmod hello.ko

# Our module is there.
sudo lsmod | grep hello

# Last message should be: hello init
dmesg -T

sudo rmmod hello

# Last message should be: hello exit
dmesg -T

# Not present anymore
sudo lsmod | grep hello

1.5.1. Hello host

Minimal host build system example:

cd hello_host_kernel_module
sudo insmod hello.ko
sudo rmmod hello.ko

1.6. Baremetal setup

1.6.1. About the baremetal setup

This setup does not use the Linux kernel nor Buildroot at all: it just runs your very own minimal OS.

x86_64 is not currently supported, only arm and aarch64: I had made some x86 bare metal examples at: but I’m lazy to port them here now. Pull requests are welcome.

The main reason this setup is included in this project, despite the word "Linux" being on the project name, is that a lot of the emulator boilerplate can be reused for both use cases.

This setup allows you to make a tiny OS and that runs just a few instructions, use it to fully control the CPU to better understand the simulators for example, or develop your own OS if you are into that.

You can also use C and a subset of the C standard library because we enable Newlib by default. See also:

Our C bare-metal compiler is built with crosstool-NG. If you have already built Buildroot previously, you will end up with two GCCs installed. Unfortunately I don’t see a solution for this, since we need separate toolchains for Newlib on baremetal and glibc on Linux:

1.6.2. Baremetal setup getting started


./build --arch aarch64 --download-dependencies qemu-baremetal
./run --arch aarch64 --baremetal interactive/prompt

You are now left inside QEMU running the tiny baremetal system baremetal/interactive/prompt.c, which uses the UART to:

  • print characters to the terminal

  • read characters from your keyboard

A session looks like this after typing abc:

enter a character
got: a
new alloc of 1 bytes at address 0x0x4000a2c8
enter a character
got: b
new alloc of 2 bytes at address 0x0x4000a2c8
enter a character
got: c
new alloc of 4 bytes at address 0x0x4000a2c8

To modify that program, edit:

vim baremetal/interactive/prompt.c

and run:

./build-baremetal --arch aarch64

./build qemu-baremetal had called build-baremetal for us previously, in addition to its requirements. ./build-baremetal uses crosstool-NG, and so it must be preceded by build-crosstool-ng, which ./build qemu-baremetal also calls.

Every .c file inside baremetal/ and .S file inside baremetal/arch/<arch>/ generates a separate baremetal image. You can run a different image with commands such as:

./run --arch aarch64 --baremetal exit
./run --arch aarch64 --baremetal arch/aarch64/add

which will run respectively:

Alternatively, for the sake of tab completion, we also accept relative paths inside baremetal/:

./run --arch aarch64 --baremetal baremetal/exit.c
./run --arch aarch64 --baremetal baremetal/arch/aarch64/add.S

Absolute paths however are used as is and must point to the actual executable:

./run --arch aarch64 --baremetal "$(./getvar --arch aarch64 baremetal_build_dir)/exit.elf"

To use gem5 instead of QEMU do:

./build --download-dependencies gem5-baremetal
./run --arch aarch64 --baremetal interactive/prompt --gem5

and then as usual open a shell with:


TODO: the carriage returns are a bit different than in QEMU, see: gem5 baremetal carriage return.

Note that ./build-baremetal requires the --gem5 option, and generates separate executable images for both, as can be seen from:

echo "$(./getvar --arch aarch64 --baremetal interactive/prompt        image)"
echo "$(./getvar --arch aarch64 --baremetal interactive/prompt --gem5 image)"

This is unlike the Linux kernel that has a single image for both QEMU and gem5:

echo "$(./getvar --arch aarch64        image)"
echo "$(./getvar --arch aarch64 --gem5 image)"

The reason for that is that on baremetal we don’t parse the device tress from memory like the Linux kernel does, which tells the kernel for example the UART address, and many other system parameters.

gem5 also supports the RealViewPBX machine, which represents an older hardware compared to the default VExpress_GEM5_V1:

./build-baremetal --arch aarch64 --gem5 --machine RealViewPBX
./run --arch aarch64 --baremetal interactive/prompt --gem5 --machine RealViewPBX

This generates yet new separate images with new magic constants:

echo "$(./getvar --arch aarch64 --baremetal interactive/prompt --gem5 --machine VExpress_GEM5_V1 image)"
echo "$(./getvar --arch aarch64 --baremetal interactive/prompt --gem5 --machine RealViewPBX      image)"

But just stick to newer and better VExpress_GEM5_V1 unless you have a good reason to use RealViewPBX.

When doing bare metal programming, it is likely that you will want to learn assembly language basics. Have a look at these tutorials for the userland part:

For more information on baremetal, see the section: Baremetal. The following subjects are particularly important:

2. GDB step debug

2.1. GDB step debug kernel boot

--wait-gdb makes QEMU and gem5 wait for a GDB connection, otherwise we could accidentally go past the point we want to break at:

./run --wait-gdb

Say you want to break at start_kernel. So on another shell:

./run-gdb start_kernel

or at a given line:

./run-gdb init/main.c:1088

Now QEMU will stop there, and you can use the normal GDB commands:


See also:

2.1.1. Disable kernel compiler optimizations

O=0 is an impossible dream, O=2 being the default.

So get ready for some weird jumps, and <value optimized out> fun. Why, Linux, why.

2.2. GDB step debug kernel post-boot

Let’s observe the kernel write system call as it reacts to some userland actions.

Start QEMU with just:


and after boot inside a shell run:


which counts to infinity to stdout. Source: rootfs_overlay/

Then in another shell, run:


and then hit:

break __x64_sys_write

And you now control the counting on the first shell from GDB!

Before v4.17, the symbol name was just sys_write, the change happened at d5a00528b58cdb2c71206e18bd021e34c4eab878. As of Linux v 4.19, the function is called sys_write in arm, and __arm64_sys_write in aarch64. One good way to find it if the name changes again is to try:

rbreak .*sys_write

or just have a quick look at the sources!

When you hit Ctrl-C, if we happen to be inside kernel code at that point, which is very likely if there are no heavy background tasks waiting, and we are just waiting on a sleep type system call of the command prompt, we can already see the source for the random place inside the kernel where we stopped.

2.3. tmux

tmux just makes things even more fun by allowing us to see both terminals at once without dragging windows around!

First start tmux with:


Now that you are inside a shell inside tmux, run:

./run --wait-gdb --tmux

Gives splits the terminal into two panes:

  • left: usual QEMU

  • right: gdb

and focuses on the GDB pane.

Now you can navigate with the usual tmux shortcuts:

  • switch between the two panes with: Ctrl-B O

  • close either pane by killing its terminal with Ctrl-D as usual

To start again, switch back to the QEMU pane, kill the emulator, and re-run:

./run --wait-gdb --tmux

This automatically clears the GDB pane, and starts a new one.

Pass extra GDB arguments with:

./run --wait-gdb --tmux=start_kernel

See the tmux manual for further details:

man tmux

2.3.1. tmux gem5

If you are using gem5 instead of QEMU, --tmux has a different effect: it opens the gem5 terminal instead of the debugger:

./run --gem5 --tmux

If you also want to use the debugger with gem5, you will need to create new terminals as usual.

From inside tmux, you can do that with Ctrl-B C or Ctrl-B %.

To see the debugger by default instead of the terminal, run:

./tmu ./run-gdb
./run --wait-gdb --gem5

2.4. GDB step debug kernel module

Loadable kernel modules are a bit trickier since the kernel can place them at different memory locations depending on load order.

So we cannot set the breakpoints before insmod.

However, the Linux kernel GDB scripts offer the lx-symbols command, which takes care of that beautifully for us.

Shell 1:


Wait for the boot to end and run:

insmod /timer.ko

This prints a message to dmesg every second.

Shell 2:


In GDB, hit Ctrl-C, and note how it says:

scanning for modules in /root/linux-kernel-module-cheat/out/kernel_modules/x86_64/kernel_modules
loading @0xffffffffc0000000: /root/linux-kernel-module-cheat/out/kernel_modules/x86_64/kernel_modules/timer.ko

That’s lx-symbols working! Now simply:

break lkmc_timer_callback

and we now control the callback from GDB!

Just don’t forget to remove your breakpoints after rmmod, or they will point to stale memory locations.

TODO: why does break work_func for insmod kthread.ko not very well? Sometimes it breaks but not others.

2.4.1. GDB step debug kernel module insmodded by init on ARM

TODO on arm 51e31cdc2933a774c2a0dc62664ad8acec1d2dbe it does not always work, and lx-symbols fails with the message:

loading vmlinux
Traceback (most recent call last):
  File "/linux-kernel-module-cheat//out/arm/buildroot/build/linux-custom/scripts/gdb/linux/", line 163, in invoke
  File "/linux-kernel-module-cheat//out/arm/buildroot/build/linux-custom/scripts/gdb/linux/", line 150, in load_all_symbols
    [self.load_module_symbols(module) for module in module_list]
  File "/linux-kernel-module-cheat//out/arm/buildroot/build/linux-custom/scripts/gdb/linux/", line 110, in load_module_symbols
    module_name = module['name'].string()
gdb.MemoryError: Cannot access memory at address 0xbf0000cc
Error occurred in Python command: Cannot access memory at address 0xbf0000cc

Can’t reproduce on x86_64 and aarch64 are fine.

It is kind of random: if you just insmod manually and then immediately ./run-gdb --arch arm, then it usually works.

But this fails most of the time: shell 1:

./run --arch arm --eval-after 'insmod /hello.ko'

shell 2:

./run-gdb --arch arm

then hit Ctrl-C on shell 2, and voila.


cat /proc/modules

says that the load address is:


so it is close to the failing 0xbf0000cc.


./run-toolchain readelf -- -s "$(./getvar kernel_modules_build_subdir)/hello.ko"

does not give any interesting hits at cc, no symbol was placed that far.

2.4.2. GDB module_init

TODO find a more convenient method. We have working methods, but they are not ideal.

This is not very easy, since by the time the module finishes loading, and lx-symbols can work properly, module_init has already finished running!

Possibly asked at: GDB module_init step into it

This is the best method we’ve found so far.

The kernel calls module_init synchronously, therefore it is not hard to step into that call.

As of 4.16, the call happens in do_one_initcall, so we can do in shell 1:


shell 2 after boot finishes (because there are other calls to do_init_module at boot, presumably for the built-in modules):

./run-gdb do_one_initcall

then step until the line:

833         ret = fn();

which does the actual call, and then step into it.

For the next time, you can also put a breakpoint there directly:

./run-gdb init/main.c:833

How we found this out: first we got GDB module_init calculate entry address working, and then we did a bt. AKA cheating :-) GDB module_init calculate entry address

This works, but is a bit annoying.

The key observation is that the load address of kernel modules is deterministic: there is a pre allocated memory region "module mapping space" filled from bottom up.

So once we find the address the first time, we can just reuse it afterwards, as long as we don’t modify the module.

Do a fresh boot and get the module:

./run --eval-after '/;insmod /fops.ko;/poweroff.out'

The boot must be fresh, because the load address changes every time we insert, even after removing previous modules.

The base address shows on terminal:

0xffffffffc0000000 .text

Now let’s find the offset of myinit:

./run-toolchain readelf -- \
  -s "$(./getvar kernel_modules_build_subdir)/fops.ko" | \
  grep myinit

which gives:

    30: 0000000000000240    43 FUNC    LOCAL  DEFAULT    2 myinit

so the offset address is 0x240 and we deduce that the function will be placed at:

0xffffffffc0000000 + 0x240 = 0xffffffffc0000240

Now we can just do a fresh boot on shell 1:

./run --eval 'insmod /fops.ko;/poweroff.out' --wait-gdb

and on shell 2:

./run-gdb '*0xffffffffc0000240'

GDB then breaks, and lx-symbols works. GDB module_init break at the end of sys_init_module

TODO not working. This could be potentially very convenient.

The idea here is to break at a point late enough inside sys_init_module, at which point lx-symbols can be called and do its magic.

Beware that there are both sys_init_module and sys_finit_module syscalls, and insmod uses fmodule_init by default.

Both call do_module_init however, which is what lx-symbols hooks to.

If we try:

b sys_finit_module

then hitting:


does not break, and insertion happens, likely because of optimizations? Disable kernel compiler optimizations

Then we try:

b do_init_module

A naive:


also fails to break!

Finally, in despair we notice that pr_debug prints the kernel load address as explained at Bypass lx-symbols.

So, if we set a breakpoint just after that message is printed by searching where that happens on the Linux source code, we must be able to get the correct load address before init_module happens. GDB module_init add trap instruction

This is another possibility: we could modify the module source by adding a trap instruction of some kind.

This appears to be described at:

But it refers to a gdbstart script which is not in the tree anymore and beyond my git log capabilities.

And just adding:

asm( " int $3");

directly gives an oops as I’d expect.

2.4.3. Bypass lx-symbols

Useless, but a good way to show how hardcore you are. Disable lx-symbols with:

./run-gdb --no-lxsymbols

From inside guest:

insmod /timer.ko
cat /proc/modules

as mentioned at:

This will give a line of form:

fops 2327 0 - Live 0xfffffffa00000000

And then tell GDB where the module was loaded with:

add-symbol-file ../../../rootfs_overlay/x86_64/timer.ko 0xffffffffc0000000

Alternatively, if the module panics before you can read /proc/modules, there is a pr_debug which shows the load address:

echo 8 > /proc/sys/kernel/printk
echo 'file kernel/module.c +p' > /sys/kernel/debug/dynamic_debug/control
/myinsmod.out /hello.ko

And then search for a line of type:

[   84.877482]  0xfffffffa00000000 .text

Tested on 4f4749148273c282e80b58c59db1b47049e190bf + 1.

2.5. GDB step debug early boot

TODO successfully debug the very first instruction that the Linux kernel runs, before start_kernel!

Break at the very first instruction executed by QEMU:

./run-gdb --no-continue

TODO why can’t we break at early startup stuff such as:

./run-gdb extract_kernel
./run-gdb main

Maybe it is because they are being copied around at specific locations instead of being run directly from inside the main image, which is where the debug information points to?

gem5 tracing with --debug-flags=Exec does show the right symbols however! So in the worst case, we can just read their source. Amazing.

v4.19 also added a CONFIG_HAVE_KERNEL_UNCOMPRESSED=y option for having the kernel uncompressed which could make following the startup easier, but it is only available on s390. aarch64 however is already uncompressed by default, so might be the easiest one. See also: vmlinux vs bzImage vs zImage vs Image.

2.5.1. GDB step debug early boot by address

One possibility is to run:

./trace-boot --arch arm

and then find the second address (the first one does not work, already too late maybe):

less "$(./getvar --arch arm trace_txt_file)"

and break there:

./run --arch arm --wait-gdb
./run-gdb --arch arm '*0x1000'

but TODO: it does not show the source assembly under arch/arm:

I also tried to hack run-gdb with:

@@ -81,7 +81,7 @@ else
 ${gdb} \
 -q \\
 -ex 'add-auto-load-safe-path $(pwd)' \\
--ex 'file vmlinux' \\
+-ex 'file arch/arm/boot/compressed/vmlinux' \\
 -ex 'target remote localhost:${port}' \\
 ${brk} \
 -ex 'continue' \\

and no I do have the symbols from arch/arm/boot/compressed/vmlinux', but the breaks still don’t work.

2.6. GDB step debug userland processes

QEMU’s -gdb GDB breakpoints are set on virtual addresses, so you can in theory debug userland processes as well.

You will generally want to use gdbserver for this as it is more reliable, but this method can overcome the following limitations of gdbserver:

  • the emulator does not support host to guest networking. This seems to be the case for gem5: gem5 host to guest networking

  • cannot see the start of the init process easily

  • gdbserver alters the working of the kernel, and makes your run less representative

Known limitations of direct userland debugging:

  • the kernel might switch context to another process or to the kernel itself e.g. on a system call, and then TODO confirm the PIC would go to weird places and source code would be missing.

  • TODO step into shared libraries. If I attempt to load them explicitly:

    (gdb) sharedlibrary ../../staging/lib/
    No loaded shared libraries match the pattern `../../staging/lib/'.

    since GDB does not know that libc is loaded.

2.6.1. GDB step debug userland custom init

This is the userland debug setup most likely to work, since at init time there is only one userland executable running.

For executables from the userland directory such as userland/count.c:

  • Shell 1:

    ./run --wait-gdb --kernel-cli 'init=/count.out'
  • Shell 2:

    ./run-gdb-user count main

    Alternatively, we could also pass the full path to the executable:

    ./run-gdb-user "$(./getvar userland_build_dir)/sleep_forever.out" main

    Path resolution is analogous to that of ./run --baremetal.

Then, as soon as boot ends, we are left inside a debug session that looks just like what gdbserver would produce.

2.6.2. GDB step debug userland BusyBox init

BusyBox custom init process:

  • Shell 1:

    ./run --wait-gdb --kernel-cli 'init=/bin/ls'
  • Shell 2:

    ./run-gdb-user "$(./getvar buildroot_build_build_dir)"/busybox-*/busybox ls_main

This follows BusyBox' convention of calling the main for each executable as <exec>_main since the busybox executable has many "mains".

BusyBox default init process:

  • Shell 1:

    ./run --wait-gdb
  • Shell 2:

    ./run-gdb-user "$(./getvar buildroot_build_build_dir)"/busybox-*/busybox init_main

init cannot be debugged with gdbserver without modifying the source, or else /sbin/init exits early with:

"must be run as PID 1"

2.6.3. GDB step debug userland non-init

Non-init process:

  • Shell 1:

    ./run --wait-gdb
  • Shell 2:

    ./run-gdb-user myinsmod main
  • Shell 1 after the boot finishes:

    /myinsmod.out /hello.ko

This is the least reliable setup as there might be other processes that use the given virtual address. GDB step debug userland non-init without --wait-gdb

TODO: without --wait-gdb and the break main that we do inside ./run-gdb-user says:

Cannot access memory at address 0x10604

and then GDB never breaks. Tested at ac8663a44a450c3eadafe14031186813f90c21e4 + 1.

The exact behaviour seems to depend on the architecture:

  • arm: happens always

  • x86_64: appears to happen only if you try to connect GDB as fast as possible, before init has been reached.

  • aarch64: could not observe the problem

We have also double checked the address with:

./run-toolchain --arch arm readelf -- \
  -s "$(./getvar --arch arm kernel_modules_build_subdir)/fops.ko" | \
  grep main

and from GDB:

info line main

and both give:


which is just 8 bytes before 0x10604.

gdbserver also says 0x10604.

However, if do a Ctrl-C in GDB, and then a direct:

b *0x000105fc

it works. Why?!

On GEM5, x86 can also give the Cannot access memory at address, so maybe it is also unreliable on QEMU, and works just by coincidence.

2.7. GDB call

However this is failing for us:

  • some symbols are not visible to call even though b sees them

  • for those that are, call fails with an E14 error

E.g.: if we break on __x64_sys_write on /

>>> call printk(0, "asdf")
Could not fetch register "orig_rax"; remote failure reply 'E14'
>>> b printk
Breakpoint 2 at 0xffffffff81091bca: file kernel/printk/printk.c, line 1824.
>>> call fdget_pos(fd)
No symbol "fdget_pos" in current context.
>>> b fdget_pos
Breakpoint 3 at 0xffffffff811615e3: fdget_pos. (9 locations)

even though fdget_pos is the first thing __x64_sys_write does:

581 SYSCALL_DEFINE3(write, unsigned int, fd, const char __user *, buf,
582         size_t, count)
583 {
584     struct fd f = fdget_pos(fd);

I also noticed that I get the same error:

Could not fetch register "orig_rax"; remote failure reply 'E14'

when trying to use:


on many (all?) functions.

2.9. GDB step debug multicore userland

For a more minimal baremetal multicore setup, see: ARM multicore.

We can set and get which cores the Linux kernel allows a program to run on with sched_getaffinity and sched_setaffinity:

./run --cpus 2 --eval-after '/sched_getaffinity.out'

Sample output:

sched_getaffinity = 1 1
sched_getcpu = 1
sched_getaffinity = 1 0
sched_getcpu = 0

Which shows us that:

  • initially:

    • all 2 cores were enabled as shown by sched_getaffinity = 1 1

    • the process was randomly assigned to run on core 1 (the second one) as shown by sched_getcpu = 1. If we run this several times, it will also run on core 0 sometimes.

  • then we restrict the affinity to just core 0, and we see that the program was actually moved to core 0

The number of cores is modified as explained at: Number of cores

taskset from the util-linux package sets the initial core affinity of a program:

./build-buildroot \
  --config 'BR2_PACKAGE_UTIL_LINUX=y' \
./run --eval-after 'taskset -c 1,1 /sched_getaffinity.out'


sched_getaffinity = 0 1
sched_getcpu = 1
sched_getaffinity = 1 0
sched_getcpu = 0

so we see that the affinity was restricted to the second core from the start.

Let’s do a QEMU observation to justify this example being in the repository with userland breakpoints.

We will run our /sched_getaffinity.out infinitely many time, on core 0 and core 1 alternatively:

./run \
  --cpus 2 \
  --wait-gdb \
  --eval-after 'i=0; while true; do taskset -c $i,$i /sched_getaffinity.out; i=$((! $i)); done' \

on another shell:

./run-gdb-user "$(./getvar userland_build_dir)/sched_getaffinity.out" main

Then, inside GDB:

(gdb) info threads
  Id   Target Id         Frame
* 1    Thread 1 (CPU#0 [running]) main () at sched_getaffinity.c:30
  2    Thread 2 (CPU#1 [halted ]) native_safe_halt () at ./arch/x86/include/asm/irqflags.h:55
(gdb) c
(gdb) info threads
  Id   Target Id         Frame
  1    Thread 1 (CPU#0 [halted ]) native_safe_halt () at ./arch/x86/include/asm/irqflags.h:55
* 2    Thread 2 (CPU#1 [running]) main () at sched_getaffinity.c:30
(gdb) c

and we observe that info threads shows the actual correct core on which the process was restricted to run by taskset!

TODO we then tried:

./run --cpus 2 --eval-after '/sched_getaffinity_threads.out'


./run-gdb-user "$(./getvar userland_build_dir)/sched_getaffinity_threads.out"

to switch between two simultaneous live threads with different affinities, it just didn’t break on our threads:

b main_thread_0


2.10. Linux kernel GDB scripts

We source the Linux kernel GDB scripts by default for lx-symbols, but they also contains some other goodies worth looking into.

Those scripts basically parse some in-kernel data structures to offer greater visibility with GDB.

All defined commands are prefixed by lx-, so to get a full list just try to tab complete that.

There aren’t as many as I’d like, and the ones that do exist are pretty self explanatory, but let’s give a few examples.

Show dmesg:


Dump the device tree to a fdtdump.dtb file in the current directory:


List inserted kernel modules:


Sample output:

Address            Module                  Size  Used by
0xffffff80006d0000 hello                  16384  0


2.10.1. lx-ps

List all processes:


Sample output:

0xffff88000ed08000 1 init
0xffff88000ed08ac0 2 kthreadd

The second and third fields are obviously PID and process name.

The first one is more interesting, and contains the address of the task_struct in memory.

This can be confirmed with:

p ((struct task_struct)*0xffff88000ed08000

which contains the correct PID for all threads I’ve tried:

pid = 1,

TODO get the PC of the kthreads: Then we would be able to see where the threads are stopped in the code!

On ARM, I tried:

task_pt_regs((struct thread_info *)((struct task_struct)*0xffffffc00e8f8000))->uregs[ARM_pc]

but task_pt_regs is a #define and GDB cannot see defines without -ggdb3: which are apparently not set?


2.11. Debug the GDB remote protocol

For when it breaks again, or you want to add a new feature!

./run --debug
./run-gdb --before '-ex "set remotetimeout 99999" -ex "set debug remote 1"' start_kernel

2.11.1. Remote 'g' packet reply is too long

This error means that the GDB server, e.g. in QEMU, sent more registers than the GDB client expected.

This can happen for the following reasons:


KGDB is kernel dark magic that allows you to GDB the kernel on real hardware without any extra hardware support.

It is useless with QEMU since we already have full system visibility with -gdb. So the goal of this setup is just to prepare you for what to expect when you will be in the treches of real hardware.

KGDB is cheaper than JTAG (free) and easier to setup (all you need is serial), but with less visibility as it depends on the kernel working, so e.g.: dies on panic, does not see boot sequence.

First run the kernel with:

./run --kgdb

this passes the following options on the kernel CLI:

kgdbwait kgdboc=ttyS1,115200

kgdbwait tells the kernel to wait for KGDB to connect.

So the kernel sets things up enough for KGDB to start working, and then boot pauses waiting for connection:

<6>[    4.866050] Serial: 8250/16550 driver, 4 ports, IRQ sharing disabled
<6>[    4.893205] 00:05: ttyS0 at I/O 0x3f8 (irq = 4, base_baud = 115200) is a 16550A
<6>[    4.916271] 00:06: ttyS1 at I/O 0x2f8 (irq = 3, base_baud = 115200) is a 16550A
<6>[    4.987771] KGDB: Registered I/O driver kgdboc
<2>[    4.996053] KGDB: Waiting for connection from remote gdb...

Entering kdb (current=0x(____ptrval____), pid 1) on processor 0 due to Keyboard Entry

KGDB expects the connection at ttyS1, our second serial port after ttyS0 which contains the terminal.

The last line is the KDB prompt, and is covered at: KDB. Typing now shows nothing because that prompt is expecting input from ttyS1.

Instead, we connect to the serial port ttyS1 with GDB:

./run-gdb --kgdb --no-continue

Once GDB connects, it is left inside the function kgdb_breakpoint.

So now we can set breakpoints and continue as usual.

For example, in GDB:


Then in QEMU:

/ &
/ pauses the kernel for KGDB, and gives control back to GDB.

And now in GDB we do the usual:

break __x64_sys_write

And now you can count from KGDB!

If you do: break __x64_sys_write immediately after ./run-gdb --kgdb, it fails with KGDB: BP remove failed: <address>. I think this is because it would break too early on the boot sequence, and KGDB is not yet ready.

See also:


TODO: we would need a second serial for KGDB to work, but it is not currently supported on arm and aarch64 with -M virt that we use:

One possible workaround for this would be to use KDB ARM.

3.2. KGDB kernel modules

Just works as you would expect:

insmod /timer.ko


break lkmc_timer_callback

and you now control the count.

3.3. KDB

KDB is a way to use KDB directly in your main console, without GDB.

Advantage over KGDB: you can do everything in one serial. This can actually be important if you only have one serial for both shell and .

Disadvantage: not as much functionality as GDB, especially when you use Python scripts. Notably, TODO confirm you can’t see the the kernel source code and line step as from GDB, since the kernel source is not available on guest (ah, if only debugging information supported full source, or if the kernel had a crazy mechanism to embed it).

Run QEMU as:

./run --kdb

This passes kgdboc=ttyS0 to the Linux CLI, therefore using our main console. Then QEMU:

[0]kdb> go

And now the kdb> prompt is responsive because it is listening to the main console.

After boot finishes, run the usual:

/ &

And you are back in KDB. Now you can count with:

[0]kdb> bp __x64_sys_write
[0]kdb> go
[0]kdb> go
[0]kdb> go
[0]kdb> go

And you will break whenever __x64_sys_write is hit.

You can get see further commands with:

[0]kdb> help

The other KDB commands allow you to step instructions, view memory, registers and some higher level kernel runtime data similar to the superior GDB Python scripts.

3.3.1. KDB graphic

You can also use KDB directly from the graphic window with:

./run --graphic --kdb

This setup could be used to debug the kernel on machines without serial, such as modern desktops.

This works because --graphics adds kbd (which stands for KeyBoarD!) to kgdboc.

3.3.2. KDB ARM

TODO neither arm and aarch64 are working as of 1cd1e58b023791606498ca509256cc48e95e4f5b + 1.

arm seems to place and hit the breakpoint correctly, but no matter how many go commands I do, the stdout simply does not show.

aarch64 seems to place the breakpoint correctly, but after the first go the kernel oopses with warning:

WARNING: CPU: 0 PID: 46 at /root/linux-kernel-module-cheat/submodules/linux/kernel/smp.c:416 smp_call_function_many+0xdc/0x358

and stack trace:


My theory is that every serious ARM developer has JTAG, and no one ever tests this, and the kernel code is just broken.

4. gdbserver

Step debug userland processes to understand how they are talking to the kernel.

First build gdbserver into the root filesystem:

./build-buildroot --config 'BR2_PACKAGE_GDB=y'

Then on guest, to debug userland/myinsmod.c:

/ /myinsmod.out /hello.ko

And on host:

./run-gdbserver myinsmod

or alternatively with the full path:

./run-gdbserver "$(./getvar userland_build_dir)/myinsmod.out"

4.1. gdbserver BusyBox

/ ls

on host you need:

./run-gdbserver "$(./getvar buildroot_build_build_dir)"/busybox-*/busybox ls_main

4.2. gdbserver libc

Our setup gives you the rare opportunity to step debug libc and other system libraries.

For example in the guest:

/ /count.out

Then on host:

./run-gdbserver count

and inside GDB:

break sleep

And you are now left inside the sleep function of our default libc implementation uclibc libc/unistd/sleep.c!

You can also step into the sleep call:


This is made possible by the GDB command that we use by default:

set sysroot ${common_buildroot_build_dir}/staging

which automatically finds unstripped shared libraries on the host for us.

5. CPU architecture

The portability of the kernel and toolchains is amazing: change an option and most things magically work on completely different hardware.

To use arm instead of x86 for example:

./build-buildroot --arch arm
./run --arch arm


./run --arch arm --wait-gdb
# On another terminal.
./run-gdb --arch arm

We also have one letter shorthand names for the architectures and --arch option:

# aarch64
./run -a A
# arm
./run -a a
# x86_64
./run -a x

Known quirks of the supported architectures are documented in this section.

5.1. x86_64

5.1.1. ring0

This example illustrates how reading from the x86 control registers with mov crX, rax can only be done from kernel land on ring0.

From kernel land:

insmod ring0.ko

works and output the registers, for example:

cr0 = 0xFFFF880080050033
cr2 = 0xFFFFFFFF006A0008
cr3 = 0xFFFFF0DCDC000

However if we try to do it from userland:


stdout gives:

Segmentation fault

and dmesg outputs:

traps: ring0.out[55] general protection ip:40054c sp:7fffffffec20 error:0 in ring0.out[400000+1000]


In both cases, we attempt to run the exact same code which is shared on the ring0.h header file.


5.2. arm

5.2.1. Run arm executable in aarch64

I’ve tried:

./run-toolchain --arch aarch64 gcc -- -static ~/test/hello_world.c -o "$(./getvar p9_dir)/a.out"
./run --arch aarch64 --eval-after '/mnt/9p/data/a.out'

but it fails with:

a.out: line 1: syntax error: unexpected word (expecting ")")

5.3. MIPS

We used to "support" it until f8c0502bb2680f2dbe7c1f3d7958f60265347005 (it booted) but dropped since one was testing it often.

If you want to revive and maintain it, send a pull request.

5.4. Other architectures

It should not be too hard to port this repository to any architecture that Buildroot supports. Pull requests are welcome.

6. init

When the Linux kernel finishes booting, it runs an executable as the first and only userland process. This executable is called the init program.

The init process is then responsible for setting up the entire userland (or destroying everything when you want to have fun).

This typically means reading some configuration files (e.g. /etc/initrc) and forking a bunch of userland executables based on those files, including the very interactive shell that we end up on.

systemd provides a "popular" init implementation for desktop distros as of 2017.

BusyBox provides its own minimalistic init implementation which Buildroot, and therefore this repo, uses by default.

The init program can be either an executable shell text file, or a compiled ELF file. It becomes easy to accept this once you see that the exec system call handles both cases equally:

The init executable is searched for in a list of paths in the root filesystem, including /init, /sbin/init and a few others. For more details see: Path to init

6.1. Replace init

To have more control over the system, you can replace BusyBox’s init with your own.

The most direct way to replace init with our own is to just use the init= command line parameter directly:

./run --kernel-cli 'init=/'

This just counts every second forever and does not give you a shell.

This method is not very flexible however, as it is hard to reliably pass multiple commands and command line arguments to the init with it, as explained at: Init environment.

For this reason, we have created a more robust helper method with the --eval option:

./run --eval 'echo "asdf qwer";insmod /hello.ko;/poweroff.out'

The --eval option replaces init with a shell script that just evals the given command.

It is basically a shortcut for:

./run --kernel-cli 'init=/ - lkmc_eval="insmod /hello.ko;/poweroff.out"'

This allows quoting and newlines by base64 encoding on host, and decoding on guest, see: Kernel command line parameters escaping.

It also automatically chooses between init= and rcinit= for you, see: Path to init

--eval replaces BusyBox' init completely, which makes things more minimal, but also has has the following consequences:

  • /etc/fstab mounts are not done, notably /proc and /sys, test it out with:

    ./run --eval 'echo asdf;ls /proc;ls /sys;echo qwer'
  • no shell is launched at the end of boot for you to interact with the system. You could explicitly add a sh at the end of your commands however:

    ./run --eval 'echo hello;sh'

The best way to overcome those limitations is to use: Run command at the end of BusyBox init

If the script is large, you can add it to a gitignored file and pass that to -E as in:

echo '
insmod /hello.ko
' >
./run --eval "$(cat"

or add it to a file to the root filesystem guest and rebuild:

echo '#!/bin/sh
insmod /hello.ko
' > rootfs_overlay/
chmod +x rootfs_overlay/
./run --kernel-cli 'init=/'

Remember that if your init returns, the kernel will panic, there are just two non-panic possibilities:

  • run forever in a loop or long sleep

  • poweroff the machine

6.1.1. poweroff.out

Just using BusyBox' poweroff at the end of the init does not work and the kernel panics:

./run --eval poweroff

because BusyBox' poweroff tries to do some fancy stuff like killing init, likely to allow userland to shutdown nicely.

But this fails when we are init itself!

poweroff works more brutally and effectively if you add -f:

./run --eval 'poweroff -f'

but why not just use our minimal /poweroff.out and be done with it?

./run --eval '/poweroff.out'

6.1.2. sleep_forever.out

I dare you to guess what this does:

./run --eval '/sleep_forever.out'

This executable is a convenient simple init that does not panic and sleeps instead.

6.1.3. time_boot.out

Get a reasonable answer to "how long does boot take?":

./run --eval-after '/time_boot.out'

Dmesg contains a message of type:

[    2.188242] time_boot.c

which tells us that boot took 2.188242 seconds.

6.2. Run command at the end of BusyBox init

Use the --eval-after option is for you rely on something that BusyBox' init set up for you like /etc/fstab:

./run --eval-after 'echo asdf;ls /proc;ls /sys;echo qwer'

After the commands run, you are left on an interactive shell.

The above command is basically equivalent to:

./run --kernel-cli-after-dash 'lkmc_eval="insmod /hello.ko;poweroff.out;"'

where the lkmc_eval option gets evaled by our default S98 startup script.

Except that --eval-after is smarter and uses base64 encoding.

Alternatively, you can also add the comamdns to run to a new init.d entry to run at the end o the BusyBox init:

cp rootfs_overlay/etc/init.d/S98 rootfs_overlay/etc/init.d/S99.gitignore
vim rootfs_overlay/etc/init.d/S99.gitignore

and they will be run automatically before the login prompt.

Scripts under /etc/init.d are run by /etc/init.d/rcS, which gets called by the line ::sysinit:/etc/init.d/rcS in /etc/inittab.

6.3. Path to init

The init is selected at:

  • initrd or initramfs system: /init, a custom one can be set with the rdinit= kernel command line parameter

  • otherwise: default is /sbin/init, followed by some other paths, a custom one can be set with init=

6.4. Init environment

The kernel parses parameters from the kernel command line up to "-"; if it doesn’t recognize a parameter and it doesn’t contain a '.', the parameter gets passed to init: parameters with '=' go into init’s environment, others are passed as command line arguments to init. Everything after "-" is passed as an argument to init.

And you can try it out with:

./run --kernel-cli 'init=/init_env_poweroff.out - asdf=qwer zxcv'




6.4.1. init environment args

The annoying dash - gets passed as a parameter to init, which makes it impossible to use this method for most non custom executables.

Arguments with dots that come after - are still treated specially (of the form subsystem.somevalue) and disappear, from args, e.g.:

./run --kernel-cli 'init=/init_env_poweroff.out - /poweroff.out'



so see how a.b is gone.

6.4.2. init environment env

Wait, where do HOME and TERM come from? (greps the kernel). Ah, OK, the kernel sets those by default:

const char *envp_init[MAX_INIT_ENVS+2] = { "HOME=/", "TERM=linux", NULL, };

6.4.3. BusyBox shell init environment

On top of the Linux kernel, the BusyBox /bin/sh shell will also define other variables.

We can explore the shenanigans that the shell adds on top of the Linux kernel with:

./run --kernel-cli 'init=/bin/sh'

From there we observe that:




therefore adding SHLVL and PWD to the default kernel exported variables.

Furthermore, to increase confusion, if you list all non-exported shell variables with:


then it shows more variables, notably:


Finally, login shells will source some default files, notably:


We currently control /root/.profile at rootfs_overlay/root/.profile, and use the default BusyBox /etc/profile.

The shell knows that it is a login shell if the first character of argv[0] is -, see also:

When we use just init=/bin/sh, the Linux kernel sets argv[0] to /bin/sh, which does not start with -.

However, if you use ::respawn:-/bin/sh on inttab described at TTY, BusyBox' init sets argv[0] to -, and so does getty. This can be observed with:

cat /proc/$$/cmdline

7. initrd

TODO: broken when we started building the Linux manually with ./build-linux instead of Buildroot. Was working before, see e.g. 56738a1c70e50bf7b6d5fbe02372c5d277a8286f.

The kernel can boot from an CPIO file, which is a directory serialization format much like tar:

The bootloader, which for us is QEMU itself, is then configured to put that CPIO into memory, and tell the kernel that it is there.

With this setup, you don’t even need to give a root filesystem to the kernel, it just does everything in memory in a ramfs.

To enable initrd instead of the default ext2 disk image, do:

./build-buildroot --initrd
./run --initrd

Notice how it boots fine, even though this leads to not giving QEMU the -drive option, as can be verified with:

cat "$(./getvar run_dir)/"

Also as expected, there is no filesystem persistency, since we are doing everything in memory:

date >f
cat f
# can't open 'f': No such file or directory

which can be good for automated tests, as it ensures that you are using a pristine unmodified system image every time.

One downside of this method is that it has to put the entire filesystem into memory, and could lead to a panic:

end Kernel panic - not syncing: Out of memory and no killable processes...

This can be solved by increasing the memory with:

./run --initrd --memory 256M

The main ingredients to get initrd working are:

7.1. initrd in desktop distros

Most modern desktop distributions have an initrd in their root disk to do early setup.

The rationale for this is described at:

One obvious use case is having an encrypted root filesystem: you keep the initrd in an unencrypted partition, and then setup decryption from there.

I think GRUB then knows read common disk formats, and then loads that initrd to memory with a /boot/grub/grub.cfg directive of type:

initrd /initrd.img-4.4.0-108-generic

7.2. initramfs

initramfs is just like initrd, but you also glue the image directly to the kernel image itself.

So the only argument that QEMU needs is the -kernel, no -drive not even -initrd! Pretty cool.

Try it out with:

./build-buildroot --initramfs -l
./run --initramfs

The -l (ell) should only be used the first time you move to / from a different root filesystem method (ext2 or cpio) to initramfs to overcome:

./build-buildroot --initramfs
./run --initramfs

It is interesting to see how this increases the size of the kernel image if you do a:

ls -lh "$(./getvar linux_image)"

before and after using initramfs, since the .cpio is now glued to the kernel image.

In the background, it uses BR2_TARGET_ROOTFS_INITRAMFS, and this makes the kernel config option CONFIG_INITRAMFS_SOURCE point to the CPIO that will be embedded in the kernel image.

8. Device tree

The device tree is a Linux kernel defined data structure that serves to inform the kernel how the hardware is setup.

platform_device contains a minimal runnable example of device tree manipulation.

Device trees serve to reduce the need for hardware vendors to patch the kernel: they just provide a device tree file instead, which is much simpler.

x86 does not use it device trees, but many other archs to, notably ARM.

This is notably because ARM boards:

  • typically don’t have discoverable hardware extensions like PCI, but rather just put everything on an SoC with magic register addresses

  • are made by a wide variety of vendors due to ARM’s licensing business model, which increases variability

The Linux kernel itself has several device trees under ./arch/<arch>/boot/dts, see also:

8.1. DTB files

Files that contain device trees have the .dtb extension when compiled, and .dts when in text form.

You can convert between those formats with:

"$(./getvar host_dir)"/bin/dtc -I dtb -O dts -o a.dts a.dtb
"$(./getvar host_dir)"/bin/dtc -I dts -O dtb -o a.dtb a.dts

Buildroot builds the tool due to BR2_PACKAGE_HOST_DTC=y.

On Ubuntu 18.04, the package is named:

sudo apt-get install device-tree-compiler

Device tree files are provided to the emulator just like the root filesystem and the Linux kernel image.

In real hardware, those components are also often provided separately. For example, on the Raspberry Pi 2, the SD card must contain two partitions:

  • the first contains all magic files, including the Linux kernel and the device tree

  • the second contains the root filesystem

8.2. Device tree syntax

Good format descriptions:

Minimal example


/ {

Check correctness with:

dtc a.dts

Separate nodes are simply merged by node path, e.g.:


/ {

/ {

then dtc a.dts gives:


/ {

8.3. Get device tree from a running kernel

This is specially interesting because QEMU and gem5 are capable of generating DTBs that match the selected machine depending on dynamic command line parameters for some types of machines.

So observing the device tree from the guest allows to easily see what the emulator has generated.

Compile the dtc tool into the root filesystem:

./build-buildroot \
  --arch aarch64 \
  --config 'BR2_PACKAGE_DTC=y' \
  --config 'BR2_PACKAGE_DTC_PROGRAMS=y' \

-M virt for example, which we use by default for aarch64, boots just fine without the -dtb option:

./run --arch aarch64

Then, from inside the guest:

dtc -I fs -O dts /sys/firmware/devicetree/base


        cpus {
                #address-cells = <0x1>;
                #size-cells = <0x0>;

                cpu@0 {
                        compatible = "arm,cortex-a57";
                        device_type = "cpu";
                        reg = <0x0>;

8.4. Device tree emulator generation

Since emulators know everything about the hardware, they can automatically generate device trees for us, which is very convenient.

This is the case for both QEMU and gem5.

For example, if we increase the number of cores to 2:

./run --arch aarch64 --cpus 2

QEMU automatically adds a second CPU to the DTB!

                cpu@0 {
                cpu@1 {

The action seems to be happening at: hw/arm/virt.c.

gem5 fs_bigLITTLE 2a9573f5942b5416fb0570cf5cb6cdecba733392 can also generate its own DTB.

gem5 can generate DTBs on ARM with --generate-dtb, but we don’t use that feature as of f8c0502bb2680f2dbe7c1f3d7958f60265347005 because it was buggy.

9. KVM

KVM is Linux kernel interface that greatly speeds up execution of virtual machines.

You can make QEMU or gem5 by passing enabling KVM with:

./run --kvm

but it was broken in gem5 with pending patches: It fails immediately on:

panic: KVM: Failed to enter virtualized mode (hw reason: 0x80000021)

KVM works by running userland instructions natively directly on the real hardware instead of running a software simulation of those instructions.

Therefore, KVM only works if you the host architecture is the same as the guest architecture. This means that this will likely only work for x86 guests since almost all development machines are x86 nowadays. Unless you are running an ARM desktop for some weird reason :-)

We don’t enable KVM by default because:

  • it limits visibility, since more things are running natively:

    • can’t use GDB

    • can’t do instruction tracing

    • on gem5, you lose cycle counts and therefor any notion of performance

  • QEMU kernel boots are already fast enough for most purposes without it

One important use case for KVM is to fast forward gem5 execution, often to skip boot, take a gem5 checkpoint, and then move on to a more detailed and slow simulation

9.1. KVM arm

TODO: we haven’t gotten it to work yet, but it should be doable, and this is an outline of how to do it. Just don’t expect this to tested very often for now.

We can test KVM on arm by running this repository inside an Ubuntu arm QEMU VM.

This produces no speedup of course, since the VM is already slow since it cannot use KVM on the x86 host.

Then, from inside that image:

sudo apt-get install git
git clone
cd linux-kernel-module-cheat
sudo ./setup -y

and then proceed exactly as in Prebuilt Buildroot setup.

We don’t want to build the full Buildroot image inside the VM as that would be way too slow, thus the recommendation for the prebuilt setup.

TODO: do the right thing and cross compile QEMU and gem5. gem5’s Python parts might be a pain. QEMU should be easy:

10. User mode simulation

Both QEMU and gem5 have an user mode simulation mode in addition to full system simulation that we consider elsewhere in this project.

In QEMU, it is called just "user mode", and in gem5 it is called syscall emulation mode.

In both, the basic idea is the same.

User mode simulation takes regular userland executables of any arch as input and executes them directly, without booting a kernel.

Instead of simulating the full system, it translates normal instructions like in full system mode, but magically forwards system calls to the host OS.

Advantages over full system simulation:

  • the simulation may run faster since you don’t have to simulate the Linux kernel and several device models

  • you don’t need to build your own kernel or root filesystem, which saves time. You still need a toolchain however, but the pre-packaged ones may work fine.


  • lower guest to host portability:

    • TODO confirm: host OS == guest OS?

    • TODO confirm: the host Linux kernel should be newer than the kernel the executable was built for.

      It may still work even if that is not the case, but could fail is a missing system call is reached.

      The target Linux kernel of the executable is a GCC toolchain build-time configuration.

  • cannot be used to test the Linux kernel, and results are less representative of a real system since we are faking more

10.1. QEMU user mode

First let’s run a dynamically linked executable built with the Buildroot toolchain:

./build-qemu --arch aarch64 --userland
./build-userland --arch aarch64
./build-buildroot --arch aarch64
./run \
  --arch aarch64 \
  --userland print_argv \
  -- \
  asdf qwer \

This runs userland/print_argv.c. --userland path resolution is analogous to that of ./run --baremetal.

./build-userland is further documented at: userland directory.

Running dynamically linked executables in QEMU requires pointing it to the root filesystem with the -L option so that it can find the dynamic linker and shared libraries.

We pass -L by default, so everything just works:

You can also try statically linked executables with:

./build-userland \
  --arch aarch64 \
  --make-args='CCFLAGS_EXTRA=-static' \
  --userland-build-id static \
./run \
  --arch aarch64 \
  --userland-build-id static \
  --userland print_argv \
  -- \
  asdf qwer \

Or you can run statically linked built by the host packaged toolchain with:

./build-userland \
  --arch aarch64 \
  --host \
  --make-args='-B CFLAGS_EXTRA=-static' \
  --userland-build-id host-static \
./run \
  --arch aarch64 \
  --userland-build-id host-static \
  --userland print_argv \
  -- \
  asdf qwer \

TODO expose dynamically linked executables built by the host toolchain. It also works, we just have to use e.g. -L /usr/aarch64-linux-gnu, so it’s not really hard, I’m just lazy.

10.1.1. QEMU user mode GDB

It’s nice when the obvious just works, right?

./run \
  --arch aarch64 \
  --userland print_argv \
  --wait-gdb \
  -- \
  asdf qwer \

and on another shell:

./run-gdb \
  --arch aarch64 \
  --userland print_argv \
  main \

Or alternatively, if you are using tmux, do everything in one go with:

./run \
  --arch aarch64 \
  --userland print_argv \
  --tmux=main \
  --wait-gdb \
  -- \
  asdf qwer \

To stop at the very first instruction of a freestanding program, just use --no-continue TODO example.

10.2. gem5 syscall emulation mode

Less robust than QEMU’s, but still usable:

There are much more unimplemented syscalls in gem5 than in QEMU. Many of those are trivial to implement however.

As of 185c2730cc78d5adda683d76c0e3b35e7cb534f0, dynamically linked executables only work on x86, and they can only use the host libraries, which is ugly:

If you try dynamically linked executables on ARM, they fail with:

fatal: Unable to open dynamic executable's interpreter.

So let’s just play with some static ones:

./build-userland \
  --arch aarch64 \
  --userland-build-id static \
  --make-args='CCFLAGS_EXTRA=-static' \
./run \
  --arch aarch64 \
  --gem5 \
  --userland print_argv \
  --userland-build-id static \
  -- \
  --options 'asdf "qw er"' \

TODO: how to escape spaces?

Step debug also works:

./run \
  --arch arm \
  --wait-gdb \
  --gem5 \
  --userland print_argv \
  --userland-build-id static \
  -- \
  --options 'asdf "qw er"' \
./run-gdb \
  --arch arm \
  --gem5 \
  --userland print_argv \
  --userland-build-id static \
  main \

10.2.1. User mode vs full system benchmark

Let’s see if user mode runs considerably faster than full system or not.

gem5 user mode:

./build-buildroot --config 'BR2_PACKAGE_DHRYSTONE=y' --arch arm
make \
  -B \
  -C "$(./getvar --arch arm buildroot_build_build_dir)/dhrystone-2" \
  CC="$(./run-toolchain --arch arm --dry gcc)" \
  CFLAGS=-static \
time \
  ./run \
  --arch arm \
  --gem5 \
  --userland \
  "$(./getvar --arch arm buildroot_build_build_dir)/dhrystone-2/dhrystone" \
  -- \
  --options 100000 \

gem5 full system:

time \
  ./run \
  --arch arm \
  --eval-after '/' \
  --gem5-readfile 'dhrystone 100000' \

QEMU user mode:

time qemu-arm "$(./getvar --arch arm buildroot_build_build_dir)/dhrystone-2/dhrystone" 100000000

QEMU full system:

time \
  ./run \
  --arch arm \
  --eval-after 'time dhrystone 100000000;/poweroff.out' \

Result on P51 at bad30f513c46c1b0995d3a10c0d9bc2a33dc4fa0:

  • gem5 user: 33 seconds

  • gem5 full system: 51 seconds

  • QEMU user: 45 seconds

  • QEMU full system: 223 seconds

11. Kernel module utilities

11.1. insmod

./run --eval-after 'insmod /hello.ko'

11.2. myinsmod

If you are feeling raw, you can insert and remove modules with our own minimal module inserter and remover!

# init_module
/myinsmod.out /hello.ko
# finit_module
/myinsmod.out /hello.ko "" 1
/myrmmod.out hello

which teaches you how it is done from C code.


The Linux kernel offers two system calls for module insertion:

  • init_module

  • finit_module


man init_module

documents that:

The finit_module() system call is like init_module(), but reads the module to be loaded from the file descriptor fd. It is useful when the authenticity of a kernel module can be determined from its location in the filesystem; in cases where that is possible, the overhead of using cryptographically signed modules to determine the authenticity of a module can be avoided. The param_values argument is as for init_module().

finit is newer and was added only in v3.8. More rationale:

11.3. modprobe

modprobe searches for modules installed under:

ls /lib/modules/<kernel_version>

and specified in the modules.order file.

This is the default install path for CONFIG_SOME_MOD=m modules built with make modules_install in the Linux kernel tree, with root path given by INSTALL_MOD_PATH, and therefore canonical in that sense.

Currently, there are only two kinds of kernel modules that you can try out with modprobe:

We are not installing out custom ./build-modules modules there, because:

11.4. kmod

The more "reference" implementation of lsmod, insmod, rmmod, etc.:

Default implementation on desktop distros such as Ubuntu 16.04, where e.g.:

ls -l /bin/lsmod


lrwxrwxrwx 1 root root 4 Jul 25 15:35 /bin/lsmod -> kmod


dpkg -l | grep -Ei


ii  kmod                                        22-1ubuntu5                                         amd64        tools for managing Linux kernel modules

BusyBox also implements its own version of those executables, see e.g. modprobe. Here we will only describe features that differ from kmod to the BusyBox implementation.

11.4.1. module-init-tools

Name of a predecessor set of tools.

11.4.2. kmod modprobe

kmod’s modprobe can also load modules under different names to avoid conflicts, e.g.:

sudo modprobe vmhgfs -o vm_hgfs

12. Filesystems

12.1. OverlayFS

OverlayFS is a filesystem merged in the Linux kernel in 3.18.

As the name suggests, OverlayFS allows you to merge multiple directories into one. The following minimal runnable examples should give you an intuition on how it works:

We are very interested in this filesystem because we are looking for a way to make host cross compiled executables appear on the guest root / without reboot.

This would have several advantages:

  • makes it faster to test modified guest programs

  • we could keep the base root filesystem very small, which implies:

    • less host disk usage, no need to copy the entire out_rootfs_overlay_dir to the image again

    • no need to worry about BR2_TARGET_ROOTFS_EXT2_SIZE

We can already make host files appear on the guest with 9P, but they appear on a subdirectory instead of the root.

If they would appear on the root instead, that would be even more awesome, because you would just use the exact same paths relative to the root transparently.

For example, we wouldn’t have to mess around with variables such as PATH and LD_LIBRARY_PATH.

The idea is to:

We already have a prototype of this running from fstab on guest at /mnt/overlay, but it has the following shortcomings:

  • changes to underlying filesystems are not visible on the overlay unless you remount with mount -r remount /mnt/overlay, as mentioned on the kernel docs:

    Changes to the underlying filesystems while part of a mounted overlay
    filesystem are not allowed.  If the underlying filesystem is changed,
    the behavior of the overlay is undefined, though it will not result in
    a crash or deadlock.

    This makes everything very inconvenient if you are inside chroot action. You would have to leave chroot, remount, then come back.

  • the overlay does not contain sub-filesystems, e.g. /proc. We would have to re-mount them. But should be doable with some automation.

Even more awesome than chroot would be to pivot_root, but I couldn’t get that working either:

12.2. Secondary disk

A simpler and possibly less overhead alternative to 9P would be to generate a secondary disk image with the benchmark you want to rebuild.

Then you can umount and re-mount on guest without reboot.

We don’t support this yet, but it should not be too hard to hack it up, maybe by hooking into rootfs-post-build-script.

This was not possible from gem5 as of 60600f09c25255b3c8f72da7fb49100e2682093a:

13. Graphics

Both QEMU and gem5 are capable of outputting graphics to the screen, and taking mouse and keyboard input.

13.1. QEMU text mode

Text mode is the default mode for QEMU.

The opposite of text mode is QEMU graphic mode

In text mode, we just show the serial console directly on the current terminal, without opening a QEMU GUI window.

You cannot see any graphics from text mode, but text operations in this mode, including:

making this a good default, unless you really need to use with graphics.

Text mode works by sending the terminal character by character to a serial device.

This is different from a display screen, where each character is a bunch of pixels, and it would be much harder to convert that into actual terminal text.

For more details, see:

Note that you can still see an image even in text mode with the VNC:

./run --vnc

and on another terminal:


but there is not terminal on the VNC window, just the CONFIG_LOGO penguin.

13.1.1. Quit QEMU from text mode

However, our QEMU setup captures Ctrl + C and other common signals and sends them to the guest, which makes it hard to quit QEMU for the first time since there is no GUI either.

The simplest way to quit QEMU, is to do:

Ctrl-A X

Alternative methods include:

13.2. QEMU graphic mode

Enable graphic mode with:

./run --graphic

Outcome: you see a penguin due to CONFIG_LOGO.

For a more exciting GUI experience, see: X11 Buildroot

Text mode is the default due to the following considerable advantages:

  • copy and paste commands and stdout output to / from host

  • get full panic traces when you start making the kernel crash :-) See also:

  • have a large scroll buffer, and be able to search it, e.g. by using tmux on host

  • one less window floating around to think about in addition to your shell :-)

  • graphics mode has only been properly tested on x86_64.

Text mode has the following limitations over graphics mode:

  • you can’t see graphics such as those produced by X11 Buildroot

  • very early kernel messages such as early console in extract_kernel only show on the GUI, since at such early stages, not even the serial has been setup.

x86_64 has a VGA device enabled by default, as can be seen as:

./qemu-monitor info qtree

and the Linux kernel picks it up through the fbdev graphics system as can be seen from:

cat /dev/urandom > /dev/fb0

13.2.2. QEMU Graphic mode arm QEMU graphic mode arm terminal

TODO: on arm, we see the penguin and some boot messages, but don’t get a shell at then end:

./run --arch aarch64 --graphic

I think it does not work because the graphic window is DRM only, i.e.:

cat /dev/urandom > /dev/fb0

fails with:

cat: write error: No space left on device

and has no effect, and the Linux kernel does not appear to have a built-in DRM console as it does for fbdev with fbcon.

There is however one out-of-tree implementation: kmscon. QEMU graphic mode arm terminal implementation

arm and aarch64 rely on the QEMU CLI option:

-device virtio-gpu-pci

and the kernel config options:


Unlike x86, arm and aarch64 don’t have a display device attached by default, thus the need for virtio-gpu-pci.

See also (recently edited and corrected by yours truly…​ :-)). QEMU graphic mode arm VGA
-device VGA
# We use virtio-gpu because the legacy VGA framebuffer is
# very troublesome on aarch64, and virtio-gpu is the only
# video device that doesn't implement it.

so maybe it is not possible?

13.3. gem5 graphic mode

gem5 does not have a "text mode", since it cannot redirect the Linux terminal to same host terminal where the executable is running: you are always forced to connect to the terminal with gem-shell.

TODO could not get it working on x86_64, only ARM.

More concretely, first build the kernel with the gem5 arm Linux kernel patches, and then run:

./build-linux \
  --arch arm \
  --custom-config-file-gem5 \
  --linux-build-id gem5-v4.15 \
./run --arch arm --gem5 --linux-build-id gem5-v4.15

and then on another shell:

vinagre localhost:5900

The CONFIG_LOGO penguin only appears after several seconds, together with kernel messages of type:

[    0.152755] [drm] found ARM HDLCD version r0p0
[    0.152790] hdlcd 2b000000.hdlcd: bound virt-encoder (ops 0x80935f94)
[    0.152795] [drm] Supports vblank timestamp caching Rev 2 (21.10.2013).
[    0.152799] [drm] No driver support for vblank timestamp query.
[    0.215179] Console: switching to colour frame buffer device 240x67
[    0.230389] hdlcd 2b000000.hdlcd: fb0:  frame buffer device
[    0.230509] [drm] Initialized hdlcd 1.0.0 20151021 for 2b000000.hdlcd on minor 0

The port 5900 is incremented by one if you already have something running on that port, gem5 stdout tells us the right port on stdout as:

system.vncserver: Listening for connections on port 5900

and when we connect it shows a message:

info: VNC client attached

Alternatively, you can also dump each new frame to an image file with --frame-capture:

./run \
  --arch arm \
  --gem5 \
  --linux-build-id gem5-v4.15 \
  -- --frame-capture \

This creates on compressed PNG whenever the screen image changes inside the m5out directory with filename of type:


It is fun to see how we get one new frame whenever the white underscore cursor appears and reappears under the penguin!

The last frame is always available uncompressed at: system.framebuffer.png.

TODO kmscube failed on aarch64 with:

kmscube[706]: unhandled level 2 translation fault (11) at 0x00000000, esr 0x92000006, in[7fbf6a6000+e000]

13.3.1. Graphic mode gem5 aarch64

For aarch64 we also need to configure the kernel with linux_config/display:

git -C "$(./getvar linux_source_dir)" fetch gem5/v4.15:gem5/v4.15
git -C "$(./getvar linux_source_dir)" checkout gem5/v4.15
./build-linux \
  --arch aarch64 \
  --config-fragment linux_config/display \
  --custom-config-file-gem5 \
  --linux-build-id gem5-v4.15 \
git -C "$(./getvar linux_source_dir)" checkout -
./run --arch aarch64 --gem5 --linux-build-id gem5-v4.15

This is because the gem5 aarch64 defconfig does not enable HDLCD like the 32 bit one arm one for some reason.

13.3.2. gem5 graphic mode DP650

TODO get working. There is an unmerged patchset at:

The DP650 is a newer display hardware than HDLCD. TODO is its interface publicly documented anywhere? Since it has a gem5 model and in-tree Linux kernel support, that information cannot be secret?

The key option to enable support in Linux is DRM_MALI_DISPLAY=y which we enable at linux_config/display.

Build the kernel exactly as for Graphic mode gem5 aarch64 and then run with:

./run --arch aarch64 --dp650 --gem5 --linux-build-id gem5-v4.15

13.3.3. Graphic mode gem5 internals

We cannot use mainline Linux because the gem5 arm Linux kernel patches are required at least to provide the CONFIG_DRM_VIRT_ENCODER option.

gem5 emulates the HDLCD ARM Holdings hardware for arm and aarch64.

The kernel uses HDLCD to implement the DRM interface, the required kernel config options are present at: linux_config/display.

TODO: minimize out the --custom-config-file. If we just remove it on arm: it does not work with a failing dmesg:

[    0.066208] [drm] found ARM HDLCD version r0p0
[    0.066241] hdlcd 2b000000.hdlcd: bound virt-encoder (ops drm_vencoder_ops)
[    0.066247] [drm] Supports vblank timestamp caching Rev 2 (21.10.2013).
[    0.066252] [drm] No driver support for vblank timestamp query.
[    0.066276] hdlcd 2b000000.hdlcd: Cannot do DMA to address 0x0000000000000000
[    0.066281] swiotlb: coherent allocation failed for device 2b000000.hdlcd size=8294400
[    0.066288] CPU: 0 PID: 1 Comm: swapper/0 Not tainted 4.15.0 #1
[    0.066293] Hardware name: V2P-AARCH64 (DT)
[    0.066296] Call trace:
[    0.066301]  dump_backtrace+0x0/0x1b0
[    0.066306]  show_stack+0x24/0x30
[    0.066311]  dump_stack+0xb8/0xf0
[    0.066316]  swiotlb_alloc_coherent+0x17c/0x190
[    0.066321]  __dma_alloc+0x68/0x160
[    0.066325]  drm_gem_cma_create+0x98/0x120
[    0.066330]  drm_fbdev_cma_create+0x74/0x2e0
[    0.066335]  __drm_fb_helper_initial_config_and_unlock+0x1d8/0x3a0
[    0.066341]  drm_fb_helper_initial_config+0x4c/0x58
[    0.066347]  drm_fbdev_cma_init_with_funcs+0x98/0x148
[    0.066352]  drm_fbdev_cma_init+0x40/0x50
[    0.066357]  hdlcd_drm_bind+0x220/0x428
[    0.066362]  try_to_bring_up_master+0x21c/0x2b8
[    0.066367]  component_master_add_with_match+0xa8/0xf0
[    0.066372]  hdlcd_probe+0x60/0x78
[    0.066377]  platform_drv_probe+0x60/0xc8
[    0.066382]  driver_probe_device+0x30c/0x478
[    0.066388]  __driver_attach+0x10c/0x128
[    0.066393]  bus_for_each_dev+0x70/0xb0
[    0.066398]  driver_attach+0x30/0x40
[    0.066402]  bus_add_driver+0x1d0/0x298
[    0.066408]  driver_register+0x68/0x100
[    0.066413]  __platform_driver_register+0x54/0x60
[    0.066418]  hdlcd_platform_driver_init+0x20/0x28
[    0.066424]  do_one_initcall+0x44/0x130
[    0.066428]  kernel_init_freeable+0x13c/0x1d8
[    0.066433]  kernel_init+0x18/0x108
[    0.066438]  ret_from_fork+0x10/0x1c
[    0.066444] hdlcd 2b000000.hdlcd: Failed to set initial hw configuration.
[    0.066470] hdlcd 2b000000.hdlcd: master bind failed: -12
[    0.066477] hdlcd: probe of 2b000000.hdlcd failed with error -12

So what other options are missing from gem5_defconfig? It would be cool to minimize it out to better understand the options.

13.4. X11 Buildroot

Once you’ve seen the CONFIG_LOGO penguin as a sanity check, you can try to go for a cooler X11 Buildroot setup.

Build and run:

./build-buildroot --config-fragment buildroot_config/x11
./run --graphic

Inside QEMU:


And then from the GUI you can start exciting graphical programs such as:




We don’t build X11 by default because it takes a considerable amount of time (about 20%), and is not expected to be used by most users: you need to pass the -x flag to enable it.

Not sure how well that graphics stack represents real systems, but if it does it would be a good way to understand how it works.

To x11 packages have an xserver prefix as in:

./build-buildroot --config-fragment buildroot_config/x11 -- xserver_xorg-server-reconfigure

the easiest way to find them out is to just list "$(./getvar buildroot_build_build_dir)/x*.

TODO as of: c2696c978d6ca88e8b8599c92b1beeda80eb62b2 I noticed that startx leads to a BUG_ON:

[    2.809104] WARNING: CPU: 0 PID: 51 at drivers/gpu/drm/ttm/ttm_bo_vm.c:304 ttm_bo_vm_open+0x37/0x40

13.4.1. X11 Buildroot mouse not moving

TODO 9076c1d9bcc13b6efdb8ef502274f846d8d4e6a1 I’m 100% sure that it was working before, but I didn’t run it forever, and it stopped working at some point. Needs bisection, on whatever commit last touched x11 stuff.

-show-cursor did not help, I just get to see the host cursor, but the guest cursor still does not move.


watch -n 1 grep i8042 /proc/interrupts

shows that interrupts do happen when mouse and keyboard presses are done, so I expect that it is some wrong either with:

  • QEMU. Same behaviour if I try the host’s QEMU 2.10.1 however.

  • X11 configuration. We do have BR2_PACKAGE_XDRIVER_XF86_INPUT_MOUSE=y.

/var/log/Xorg.0.log contains the following interesting lines:

[    27.549] (II) LoadModule: "mouse"
[    27.549] (II) Loading /usr/lib/xorg/modules/input/
[    27.590] (EE) <default pointer>: Cannot find which device to use.
[    27.590] (EE) <default pointer>: cannot open input device
[    27.590] (EE) PreInit returned 2 for "<default pointer>"
[    27.590] (II) UnloadModule: "mouse"

The file /dev/inputs/mice does not exist.

Note that our current link:kernel_confi_fragment sets:


for gem5, so you might want to remove those lines to debug this.

13.4.2. X11 Buildroot ARM

On ARM, startx hangs at a message:

vgaarb: this pci device is not a vga device

and nothing shows on the screen, and:

grep EE /var/log/Xorg.0.log


(EE) Failed to load module "modesetting" (module does not exist, 0)

A friend told me this but I haven’t tried it yet:

  • xf86-video-modesetting is likely the missing ingredient, but it does not seem possible to activate it from Buildroot currently without patching things.

  • xf86-video-fbdev should work as well, but we need to make sure fbdev is enabled, and maybe add some line to the Xorg.conf

14. Networking

14.1. Enable networking

We disable networking by default because it starts an userland process, and we want to keep the number of userland processes to a minimum to make the system more understandable: Resource tradeoff guidelines

To enable networking on Buildroot, simply run:

ifup -a

That command goes over all (-a) the interfaces in /etc/network/interfaces and brings them up.

Then test it with:

cat index.html

Disable networking with:

ifdown -a

To enable networking by default after boot, use the methods documented at Run command at the end of BusyBox init.

14.2. ping

ping does not work within QEMU by default, e.g.:


hangs after printing the header:

PING ( 56 data bytes

14.3. Guest host networking

In this section we discuss how to interact between the guest and the host through networking.

First ensure that you can access the external network since that is easier to get working: Networking.

14.3.1. Host to guest networking nc host to guest

With nc we can create the most minimal example possible as a sanity check.

On guest run:

nc -l -p 45455

Then on host run:

echo asdf | nc localhost 45455

asdf appears on the guest.

This uses:

  • BusyBox' nc utility, which is enabled with CONFIG_NC=y

  • nc from the netcat-openbsd package on an Ubuntu 18.04 host

Only this specific port works by default since we have forwarded it on the QEMU command line.

We us this exact procedure to connect to gdbserver. ssh into guest

Not enabled by default due to the build / runtime overhead. To enable, build with:

./build-buildroot --config 'BR2_PACKAGE_OPENSSH=y'

Then inside the guest turn on sshd:


And finally on host:

ssh root@localhost -p 45456 gem5 host to guest networking

Could not do port forwarding from host to guest, and therefore could not use gdbserver:

14.3.2. Guest to host networking

TODO I never got this to work.

There is guestfwd, which sounds analogous to hostwfd used in the other sense, but I was not able to get it working, e.g.:

-netdev user,hostfwd=tcp::45455-:45455,guestfwd=tcp::45456-,id=net0 \


Could not open guest forwarding device 'guestfwd.tcp.45456'

14.4. 9P

The 9p protocol allows the guest to mount a host directory.

Both QEMU and 9P gem5 support 9P.

14.4.1. 9P vs NFS

All of 9P and NFS (and sshfs) allow sharing directories between guest and host.

Advantages of 9P

  • we haven’t managed to do Guest to host networking, which prevents us from mounting a host directory on the guest

    Furthermore, this would require sudo on the host to mount

  • we could share a guest directory to the host, but this would require running a server on the guest, which adds simulation overhead

    Furthermore, this would be inconvenient, since what we usually want to do is to share host cross built files with the guest, and to do that we would have to copy the files over after the guest starts the server.

  • QEMU implements 9P natively, which makes it very stable and convenient, and must mean it is a simpler protocol than NFS as one would expect.

    This is not the case for gem5 7bfb7f3a43f382eb49853f47b140bfd6caad0fb8 unfortunately, which relies on the diod host daemon, although it is not unfeasible that future versions could implement it natively as well.

Advantages of NFS:

  • way more widely used and therefore stable and available, not to mention that it also works on real hardware.

  • the name does not start with a digit, which is an invalid identifier in all programming languages known to man. Who in their right mind would call a software project as such? It does not even match the natural order of Plan 9; Plan then 9: P9!

14.4.2. 9P getting started

As usual, we have already set everything up for you. On host:

cd "$(./getvar p9_dir)"
uname -a > host


cd /mnt/9p/data
cat host
uname -a > guest


cat guest

The main ingredients for this are:


15. Linux kernel

15.1. Linux kernel configuration

15.1.1. Modify kernel config

By default, we use a .config that is a mixture of:

  • Buildroot’s minimal per machine .config, which has the minimal options needed to boot

  • our kernel configs which enables options we want to play with

To modify a single option on top of our defaults, do:

./build-linux --config 'CONFIG_FORTIFY_SOURCE=y'

Kernel modules depend on certain kernel configs, and therefore in general you might have to clean and rebuild the kernel modules after changing the kernel config:

./build-modules --clean

and then proceed as in Your first kernel module hack.

You might often get way without rebuilding the kernel modules however.

To use an extra kernel config fragment file on top of our defaults, do:

printf '
' > data/myconfig
./build-linux --config-fragment 'data/myconfig'

To use just your own exact .config instead of our defaults ones, use:

./build-linux --custom-config-file data/myconfig

The following options can all be used together, sorted by decreasing config setting power precedence:

  • --config

  • --config-fragment

  • --custom-config-file

15.1.2. Find the kernel config

Ge the build config in guest:

zcat /proc/config.gz

or with our shortcut:


or to conveniently grep for a specific option case insensitively:

/ ikconfig

This is enabled by:


From host:

cat "$(./getvar linux_build_dir)/.config"
./linux/scripts/extract-ikconfig "$(./getvar vmlinux)"

although this can be useful when someone gives you a random image.

15.1.3. About our Linux kernel configs

All our Linux kernel configs are stored under linux_config/.

To find out which kernel configs are being used, simply run:

./build-linux --dry-run

and look for the call. This script from the Linux kernel tree, as the name suggests, merges multiple configuration files into one as explained at:

For each arch, the base of our configs are named as:


These configs are extracted directly from a Buildroot build with update-buildroot-kernel-config.

Note that Buildroot can sed override some of the configurations, e.g. it forces CONFIG_BLK_DEV_INITRD=y when BR2_TARGET_ROOTFS_CPIO is on. For this reason, those configs are not simply copy pasted from Buildroot files, but rather from a Buildroot kernel build, and then minimized with make savedefconfig.

On top of those, we add the following by default:

  • linux_config/min: minimal tweaks required to boot gem5 or for using our slightly different QEMU command line options than Buildroot on all archs

    Having the same config working for both QEMU and gem5 (oh, the hours of bisection) means that you can deal with functional matters in QEMU, which runs much faster, and switch to gem5 only for performance issues.

  • linux_config/default: other optional configs that we enable by default because they increase visibility, or expose some cool feature, and don’t significantly increase build time nor add significant runtime overhead About Buildroot’s kernel configs

To see Buildroot’s base configs, start from buildroot/configs/qemu_x86_64_defconfig.

That file contains BR2_LINUX_KERNEL_CUSTOM_CONFIG_FILE="board/qemu/x86_64/linux-4.15.config", which points to the base config file used: board/qemu/x86_64/linux-4.15.config.

arm, on the other hand, uses buildroot/configs/qemu_arm_vexpress_defconfig, which contains BR2_LINUX_KERNEL_DEFCONFIG="vexpress", and therefore just does a make vexpress_defconfig, and gets its config from the Linux kernel tree itself. Notable alternate gem5 kernel configs

Other configs which we had previously tested at 4e0d9af81fcce2ce4e777cb82a1990d7c2ca7c1e are:

15.2. Kernel version

15.2.1. Find the kernel version

We try to use the latest possible kernel major release version.


cat /proc/version

or in the source:

cd "$(./getvar linux_source_dir)"
git log | grep -E '    Linux [0-9]+\.' | head

15.2.2. Update the Linux kernel

During update all you kernel modules may break since the kernel API is not stable.

They are usually trivial breaks of things moving around headers or to sub-structs.

The userland, however, should simply not break, as Linus enforces strict backwards compatibility of userland interfaces.

This backwards compatibility is just awesome, it makes getting and running the latest master painless.

This also makes this repo the perfect setup to develop the Linux kernel.

In case something breaks while updating the Linux kernel, you can try to bisect it to understand the root cause: Bisection.

15.2.3. Downgrade the Linux kernel

The kernel is not forward compatible, however, so downgrading the Linux kernel requires downgrading the userland too to the latest Buildroot branch that supports it.

The default Linux kernel version is bumped in Buildroot with commit messages of type:

linux: bump default to version 4.9.6

So you can try:

git log --grep 'linux: bump default to version'

Those commits change BR2_LINUX_KERNEL_LATEST_VERSION in /linux/

You should then look up if there is a branch that supports that kernel. Staying on branches is a good idea as they will get backports, in particular ones that fix the build as newer host versions come out.

Finally, after downgrading Buildroot, if something does not work, you might also have to make some changes to how this repo uses Buildroot, as the Buildroot configuration options might have changed.

We don’t expect those changes to be very difficult. A good way to approach the task is to:

  • do a dry run build to get the equivalent Bash commands used:

    ./build-buildroot --dry-run
  • build the Buildroot documentation for the version you are going to use, and check if all Buildroot build commands make sense there

Then, if you spot an option that is wrong, some grepping in this repo should quickly point you to the code you need to modify.

It also possible that you will need to apply some patches from newer Buildroot versions for it to build, due to incompatibilities with the host Ubuntu packages and that Buildroot version. Just read the error message, and try:

  • git log master — packages/<pkg>

  • Google the error message for mailing list hits

Successful port reports:

15.3. Kernel command line parameters

Bootloaders can pass a string as input to the Linux kernel when it is booting to control its behaviour, much like the execve system call does to userland processes.

This allows us to control the behaviour of the kernel without rebuilding anything.

With QEMU, QEMU itself acts as the bootloader, and provides the -append option and we expose it through ./run --kernel-cli, e.g.:

./run --kernel-cli 'foo bar'

Then inside the host, you can check which options were given with:

cat /proc/cmdline

They are also printed at the beginning of the boot message:

dmesg | grep "Command line"

See also:

The arguments are documented in the kernel documentation:

When dealing with real boards, extra command line options are provided on some magic bootloader configuration file, e.g.:

15.3.1. Kernel command line parameters escaping

Double quotes can be used to escape spaces as in opt="a b", but double quotes themselves cannot be escaped, e.g. opt"a\"b"

This even lead us to use base64 encoding with --eval!

15.3.2. Kernel command line parameters definition points

There are two methods:

  • __setup as in:

    __setup("console=", console_setup);
  • core_param as in:

    core_param(panic, panic_timeout, int, 0644);

core_param suggests how they are different:

 * core_param - define a historical core kernel parameter.


 * core_param is just like module_param(), but cannot be modular and
 * doesn't add a prefix (such as "printk.").  This is for compatibility
 * with __setup(), and it makes sense as truly core parameters aren't
 * tied to the particular file they're in.

15.3.3. rw

By default, the Linux kernel mounts the root filesystem as readonly. TODO rationale?

This cannot be observed in the default BusyBox init, because by default our rootfs_overlay/etc/inittab does:

/bin/mount -o remount,rw /

Analogously, Ubuntu 18.04 does in its fstab something like:

UUID=/dev/sda1 / ext4 errors=remount-ro 0 1

which uses default mount rw flags.

We have however removed those setups init setups to keep things more minimal, and replaced them with the rw kernel boot parameter makes the root mounted as writable.

To observe the default readonly behaviour, hack the run script to remove replace init, and then run on a raw shell:

./run --kernel-cli 'init=/bin/sh'

Now try to do:

touch a

which fails with:

touch: a: Read-only file system

We can also observe the read-onlyness with:

mount -t proc /proc

which contains:

/dev/root on / type ext2 (ro,relatime,block_validity,barrier,user_xattr)

and so it is Read Only as shown by ro.

15.3.4. norandmaps

Disable userland address space randomization. Test it out by running rand_check.out twice:

./run --eval-after '/rand_check.out;/poweroff.out'
./run --eval-after '/rand_check.out;/poweroff.out'

If we remove it from our run script by hacking it up, the addresses shown by rand_check.out vary across boots.

Equivalent to:

echo 0 > /proc/sys/kernel/randomize_va_space

15.4. printk

printk is the most simple and widely used way of getting information from the kernel, so you should familiarize yourself with its basic configuration.

We use printk a lot in our kernel modules, and it shows on the terminal by default, along with stdout and what you type.

Hide all printk messages:

dmesg -n 1

or equivalently:

echo 1 > /proc/sys/kernel/printk

Do it with a Kernel command line parameters to affect the boot itself:

./run --kernel-cli 'loglevel=5'

and now only boot warning messages or worse show, which is useful to identify problems.

Our default printk format is:



<6>[    2.979121] Freeing unused kernel memory: 2024K


  • LEVEL: higher means less serious

  • TIMESTAMP: seconds since boot

This format is selected by the following boot options:

  • console_msg_format=syslog: add the <LEVEL> part. Added in v4.16.

  • printk.time=y: add the [TIMESTAMP] part

The debug highest level is a bit more magic, see: pr_debug for more info.

15.4.1. ignore_loglevel

./run --kernel-cli 'ignore_loglevel'

enables all log levels, and is basically the same as:

./run --kernel-cli 'loglevel=8'

except that you don’t need to know what is the maximum level.

15.4.2. pr_debug

Debug messages are not printable by default without recompiling.

But the awesome CONFIG_DYNAMIC_DEBUG=y option which we enable by default allows us to do:

echo 8 > /proc/sys/kernel/printk
echo 'file kernel/module.c +p' > /sys/kernel/debug/dynamic_debug/control
/myinsmod.out /hello.ko

and we have a shortcut at:


Wildcards are also accepted, e.g. enable all messages from all files:

echo 'file * +p' > /sys/kernel/debug/dynamic_debug/control

TODO: why is this not working:

echo 'func sys_init_module +p' > /sys/kernel/debug/dynamic_debug/control

Enable messages in specific modules:

echo 8 > /proc/sys/kernel/printk
echo 'module myprintk +p' > /sys/kernel/debug/dynamic_debug/control
insmod /myprintk.ko

This outputs the pr_debug message:

printk debug

but TODO: it also shows debug messages even without enabling them explicitly:

echo 8 > /proc/sys/kernel/printk
insmod /myprintk.ko

and it shows as enabled:

# grep myprintk /sys/kernel/debug/dynamic_debug/control
/root/linux-kernel-module-cheat/out/kernel_modules/x86_64/kernel_modules/panic.c:12 [myprintk]myinit =p "pr_debug\012"

Enable pr_debug for boot messages as well, before we can reach userland and write to /proc:

./run --kernel-cli 'dyndbg="file * +p" loglevel=8'

Get ready for the noisiest boot ever, I think it overflows the printk buffer and funny things happen. pr_debug != printk(KERN_DEBUG

When CONFIG_DYNAMIC_DEBUG is set, printk(KERN_DEBUG is not the exact same as pr_debug( since printk(KERN_DEBUG messages are visible with:

./run --kernel-cli 'initcall_debug logleve=8'

which outputs lines of type:

<7>[    1.756680] calling  clk_disable_unused+0x0/0x130 @ 1
<7>[    1.757003] initcall clk_disable_unused+0x0/0x130 returned 0 after 111 usecs

which are printk(KERN_DEBUG inside init/main.c in v4.16.

This likely comes from the ifdef split at init/main.c:

/* If you are writing a driver, please use dev_dbg instead */
#include <linux/dynamic_debug.h>

/* dynamic_pr_debug() uses pr_fmt() internally so we don't need it here */
#define pr_debug(fmt, ...) \
    dynamic_pr_debug(fmt, ##__VA_ARGS__)
#elif defined(DEBUG)
#define pr_debug(fmt, ...) \
    printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__)
#define pr_debug(fmt, ...) \
    no_printk(KERN_DEBUG pr_fmt(fmt), ##__VA_ARGS__)

15.6. Kernel module APIs

15.6.1. Kernel module parameters

The Linux kernel allows passing module parameters at insertion time through the init_module and finit_module system calls:

echo $?

Outcome: the test passes:



As shown in the example, module parameters can also be read and modified at runtime from sysfs.

We can obtain the help text of the parameters with:

modinfo /params.ko

The output contains:

parm:           j:my second favorite int
parm:           i:my favorite int modprobe.conf

modprobe insertion can also set default parameters via the /etc/modprobe.conf file:

modprobe params
cat /sys/kernel/debug/lkmc_params


12 34

This is specially important when loading modules with Kernel module dependencies or else we would have no opportunity of passing those.

15.6.2. Kernel module dependencies

One module can depend on symbols of another module that are exported with EXPORT_SYMBOL:

echo $?

Outcome: the test passes:



The kernel deduces dependencies based on the EXPORT_SYMBOL that each module uses.

Symbols exported by EXPORT_SYMBOL can be seen with:

insmod /dep.ko
grep lkmc_dep /proc/kallsyms

sample output:

ffffffffc0001030 r __ksymtab_lkmc_dep   [dep]
ffffffffc000104d r __kstrtab_lkmc_dep   [dep]
ffffffffc0002300 B lkmc_dep     [dep]

This requires CONFIG_KALLSYMS_ALL=y.

Dependency information is stored by the kernel module build system in the .ko files' MODULE_INFO, e.g.:

modinfo /dep2.ko


depends:        dep

We can double check with:

strings 3 /dep2.ko  | grep -E 'depends'

The output contains:


Module dependencies are also stored at:

cd /lib/module/*
grep dep modules.dep


extra/dep2.ko: extra/dep.ko

TODO: what for, and at which point point does Buildroot / BusyBox generate that file? Kernel module dependencies with modprobe

Unlike insmod, modprobe deals with kernel module dependencies for us.

First get kernel_modules package working.

Then, for example:

modprobe buildroot_dep2

outputs to dmesg:


and then:



Module                  Size  Used by    Tainted: G
buildroot_dep2         16384  0
buildroot_dep          16384  1 buildroot_dep2


Removal also removes required modules that have zero usage count:

modprobe -r buildroot_dep2

modprobe uses information from the modules.dep file to decide the required dependencies. That file contains:

extra/buildroot_dep2.ko: extra/buildroot_dep.ko



Module metadata is stored on module files at compile time. Some of the fields can be retrieved through the THIS_MODULE struct module:

insmod /module_info.ko

Dmesg output:

name = module_info
version = 1.0

Some of those are also present on sysfs:

cat /sys/module/module_info/version



And we can also observe them with the modinfo command line utility:

modinfo /module_info.ko

sample output:

filename:       /module_info.ko
license:        GPL
version:        1.0
srcversion:     AF3DE8A8CFCDEB6B00E35B6
vermagic:       4.17.0 SMP mod_unload modversions

Module information is stored in a special .modinfo section of the ELF file:

./run-toolchain readelf -- -SW "$(./getvar target_dir)/module_info.ko"


  [ 5] .modinfo          PROGBITS        0000000000000000 0000d8 000096 00   A  0   0  8


./run-toolchain readelf -- -x .modinfo "$(./getvar buildroot_build_build_dir)/module_info.ko"


  0x00000000 6c696365 6e73653d 47504c00 76657273 license=GPL.vers
  0x00000010 696f6e3d 312e3000 61736466 3d717765 ion=1.0.asdf=qwe
  0x00000020 72000000 00000000 73726376 65727369 r.......srcversi
  0x00000030 6f6e3d41 46334445 38413843 46434445 on=AF3DE8A8CFCDE
  0x00000040 42364230 30453335 42360000 00000000 B6B00E35B6......
  0x00000050 64657065 6e64733d 006e616d 653d6d6f
  0x00000060 64756c65 5f696e66 6f007665 726d6167 dule_info.vermag
  0x00000070 69633d34 2e31372e 3020534d 50206d6f ic=4.17.0 SMP mo
  0x00000080 645f756e 6c6f6164 206d6f64 76657273 d_unload modvers
  0x00000090 696f6e73 2000                       ions .

I think a dedicated section is used to allow the Linux kernel and command line tools to easily parse that information from the ELF file as we’ve done with readelf.


15.6.4. vermagic

Vermagic is a magic string present in the kernel and on MODULE_INFO of kernel modules. It is used to verify that the kernel module was compiled against a compatible kernel version and relevant configuration:

insmod /vermagic.ko

Possible dmesg output:

VERMAGIC_STRING = 4.17.0 SMP mod_unload modversions

If we artificially create a mismatch with MODULE_INFO(vermagic, the insmod fails with:

insmod: can't insert '/vermagic_fail.ko': invalid module format

and dmesg says the expected and found vermagic found:

vermagic_fail: version magic 'asdfqwer' should be '4.17.0 SMP mod_unload modversions '

The kernel’s vermagic is defined based on compile time configurations at include/linux/vermagic.h:

#define VERMAGIC_STRING                                                 \
        UTS_RELEASE " "                                                 \
        MODULE_ARCH_VERMAGIC                                            \

The SMP part of the string for example is defined on the same file based on the value of CONFIG_SMP:


TODO how to get the vermagic from running kernel from userland?

kmod modprobe has a flag to skip the vermagic check:


This option just strips modversion information from the module before loading, so it is not a kernel feature.

15.6.5. module_init

init_module and cleantup_module are an older alternative to the module_init and module_exit macros:

insmod /init_module.ko
rmmod init_module

Dmesg output:


15.7. Kernel panic and oops

To test out kernel panics and oops in controlled circumstances, try out the modules:

insmod /panic.ko
insmod /oops.ko


A panic can also be generated with:

echo c > /proc/sysrq-trigger

How to generate them:

When a panic happens, Shift-PgUp does not work as it normally does, and it is hard to get the logs if on are on QEMU graphic mode:

15.7.1. Kernel panic

On panic, the kernel dies, and so does our terminal.

The panic trace looks like:

panic: loading out-of-tree module taints kernel.
panic myinit
Kernel panic - not syncing: hello panic
CPU: 0 PID: 53 Comm: insmod Tainted: G           O     4.16.0 #6
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 04/01/2014
Call Trace:
 ? 0xffffffffc0000000
 ? printk+0x43/0x4b
 ? 0xffffffffc0000000
 myinit+0x1d/0x20 [panic]
 ? kernel_read_file+0x7d/0x140
 ? SyS_finit_module+0xa8/0xb0
 ? trace_hardirqs_off_thunk+0x1a/0x32
RIP: 0033:0x7ffff7b36206
RSP: 002b:00007fffffffeb78 EFLAGS: 00000206 ORIG_RAX: 0000000000000139
RAX: ffffffffffffffda RBX: 000000000000005c RCX: 00007ffff7b36206
RDX: 0000000000000000 RSI: 000000000069e010 RDI: 0000000000000003
RBP: 000000000069e010 R08: 00007ffff7ddd320 R09: 0000000000000000
R10: 00007ffff7ddd320 R11: 0000000000000206 R12: 0000000000000003
R13: 00007fffffffef4a R14: 0000000000000000 R15: 0000000000000000
Kernel Offset: disabled
---[ end Kernel panic - not syncing: hello panic

Notice how our panic message hello panic is visible at:

Kernel panic - not syncing: hello panic Kernel module stack trace to source line

The log shows which module each symbol belongs to if any, e.g.:

myinit+0x1d/0x20 [panic]

says that the function myinit is in the module panic.

To find the line that panicked, do:


and then:

info line *(myinit+0x1d)

which gives us the correct line:

Line 7 of "/root/linux-kernel-module-cheat/out/kernel_modules/x86_64/kernel_modules/panic.c" starts at address 0xbf00001c <myinit+28> and ends at 0xbf00002c <myexit>.

The exact same thing can be done post mortem with:

./run-toolchain gdb -- \
  -batch \
  -ex 'info line *(myinit+0x1d)' \
  "$(./getvar kernel_modules_build_subdir)/panic.ko" \

Related: BUG_ON

Basically just calls panic("BUG!") for most archs. Exit emulator on panic

For testing purposes, it is very useful to quit the emulator automatically with exit status non zero in case of kernel panic, instead of just hanging forever. Exit QEMU on panic

Enabled by default with:

  • panic=-1 command line option which reboots the kernel immediately on panic, see: Reboot on panic

  • QEMU -no-reboot, which makes QEMU exit when the guest tries to reboot

Also asked at which also mentions the x86_64 -device pvpanic, but I don’t see much advantage to it.

TODO neither method exits with exit status different from 0, so for now we are just grepping the logs for panic messages, which sucks.

One possibility that gets close would be to use GDB step debug to break at the panic function, and then send a QEMU monitor from GDB quit command if that happens, but I don’t see a way to exit with non-zero status to indicate error. Exit gem5 on panic

gem5 actually detects panics automatically by parsing kernel symbols and detecting when the PC reaches the address of the panic function. gem5 then prints to stdout:

Kernel panic in simulated kernel

and exits with status -6.

We enable the system.panic_on_panic option by default on arm and aarch64, which makes gem5 exit immediately in case of panic, which is awesome!

If we don’t set system.panic_on_panic, then gem5 just hangs.

TODO: why doesn’t x86 support system.panic_on_panic as well? Trying to set system.panic_on_panic there fails with:

AttributeError: Class LinuxX86System has no parameter panic_on_panic

However, as of f9eb0b72de9029ff16091a18de109c18a9ecc30a, panic on x86 makes gem5 crash with:

panic: i8042 "System reset" command not implemented.

which is a good side effect of an unimplemented hardware feature, since the simulation actually stops.

        kernelPanicEvent = addKernelFuncEventOrPanic<Linux::KernelPanicEvent>(
            "panic", "Kernel panic in simulated kernel", dmesg_output);

Here we see that the symbol "panic" for the panic() function is the one being tracked. Reboot on panic

Make the kernel reboot after n seconds after panic:

echo 1 > /proc/sys/kernel/panic

Can also be controlled with the panic= kernel boot parameter.

0 to disable, -1 to reboot immediately.

Bibliography: Panic trace show addresses instead of symbols

If CONFIG_KALLSYMS=n, then addresses are shown on traces instead of symbol plus offset.

In v4.16 it does not seem possible to configure that at runtime. GDB step debugging with:

./run --eval-after 'insmod /dump_stack.ko' --wait-gdb --tmux=dump_stack

shows that traces are printed at arch/x86/kernel/dumpstack.c:

static void printk_stack_address(unsigned long address, int reliable,
                 char *log_lvl)
    printk("%s %s%pB\n", log_lvl, reliable ? "" : "? ", (void *)address);

and %pB is documented at Documentation/core-api/printk-formats.rst:

If KALLSYMS are disabled then the symbol address is printed instead.

I wasn’t able do disable CONFIG_KALLSYMS to test this this out however, it is being selected by some other option? But I then used make menuconfig to see which options select it, and they were all off…​

15.7.2. Kernel oops

On oops, the shell still lives after.

However we:

  • leave the normal control flow, and oops after never gets printed: an interrupt is serviced

  • cannot rmmod oops afterwards

It is possible to make oops lead to panics always with:

echo 1 > /proc/sys/kernel/panic_on_oops
insmod /oops.ko

An oops stack trace looks like:

BUG: unable to handle kernel NULL pointer dereference at 0000000000000000
IP: myinit+0x18/0x30 [oops]
PGD dccf067 P4D dccf067 PUD dcc1067 PMD 0
Oops: 0002 [#1] SMP NOPTI
Modules linked in: oops(O+)
CPU: 0 PID: 53 Comm: insmod Tainted: G           O     4.16.0 #6
Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 04/01/2014
RIP: 0010:myinit+0x18/0x30 [oops]
RSP: 0018:ffffc900000d3cb0 EFLAGS: 00000282
RAX: 000000000000000b RBX: ffffffffc0000000 RCX: ffffffff81e3e3a8
RDX: 0000000000000001 RSI: 0000000000000086 RDI: ffffffffc0001033
RBP: ffffc900000d3e30 R08: 69796d2073706f6f R09: 000000000000013b
R10: ffffea0000373280 R11: ffffffff822d8b2d R12: 0000000000000000
R13: ffffffffc0002050 R14: ffffffffc0002000 R15: ffff88000dc934c8
FS:  00007ffff7ff66a0(0000) GS:ffff88000fc00000(0000) knlGS:0000000000000000
CS:  0010 DS: 0000 ES: 0000 CR0: 0000000080050033
CR2: 0000000000000000 CR3: 000000000dcd2000 CR4: 00000000000006f0
Call Trace:
 ? SyS_finit_module+0xa8/0xb0
 ? trace_hardirqs_off_thunk+0x1a/0x32
RIP: 0033:0x7ffff7b36206
RSP: 002b:00007fffffffeb78 EFLAGS: 00000206 ORIG_RAX: 0000000000000139
RAX: ffffffffffffffda RBX: 000000000000005c RCX: 00007ffff7b36206
RDX: 0000000000000000 RSI: 000000000069e010 RDI: 0000000000000003
RBP: 000000000069e010 R08: 00007ffff7ddd320 R09: 0000000000000000
R10: 00007ffff7ddd320 R11: 0000000000000206 R12: 0000000000000003
R13: 00007fffffffef4b R14: 0000000000000000 R15: 0000000000000000
Code: <c7> 04 25 00 00 00 00 00 00 00 00 e8 b2 33 09 c1 31 c0 c3 0f 1f 44
RIP: myinit+0x18/0x30 [oops] RSP: ffffc900000d3cb0
CR2: 0000000000000000
---[ end trace 3cdb4e9d9842b503 ]---

To find the line that oopsed, look at the RIP register:

RIP: 0010:myinit+0x18/0x30 [oops]

and then on GDB:



info line *(myinit+0x18)

which gives us the correct line:

Line 7 of "/root/linux-kernel-module-cheat/out/kernel_modules/x86_64/kernel_modules/panic.c" starts at address 0xbf00001c <myinit+28> and ends at 0xbf00002c <myexit>.

This-did not work on arm due to GDB step debug kernel module insmodded by init on ARM so we need to either:

15.7.3. dump_stack

The dump_stack function produces a stack trace much like panic and oops, but causes no problems and we return to the normal control flow, and can cleanly remove the module afterwards:

insmod /dump_stack.ko

15.7.4. WARN_ON

The WARN_ON macro basically just calls dump_stack.

One extra side effect is that we can make it also panic with:

echo 1 > /proc/sys/kernel/panic_on_warn
insmod /warn_on.ko

Can also be activated with the panic_on_warn boot parameter.

15.8. Pseudo filesystems

Pseudo filesystems are filesystems that don’t represent actual files in a hard disk, but rather allow us to do special operations on filesystem-related system calls.

What each pseudo-file does for each related system call does is defined by its File operations.


15.8.1. debugfs

Debugfs is the simplest pseudo filesystem to play around with:

echo $?

Outcome: the test passes:



Debugfs is made specifically to help test kernel stuff. Just mount, set File operations, and we are done.

For this reason, it is the filesystem that we use whenever possible in our tests. explicitly mounts a debugfs at a custom location, but the most common mount point is /sys/kernel/debug.

This mount not done automatically by the kernel however: we, like most distros, do it from userland with our fstab.

Debugfs support requires the kernel to be compiled with CONFIG_DEBUG_FS=y.

Only the more basic file operations can be implemented in debugfs, e.g. mmap never gets called:

15.8.2. procfs

Procfs is just another fops entry point:

echo $?

Outcome: the test passes:


Procfs is a little less convenient than debugfs, but is more used in serious applications.

Procfs can run all system calls, including ones that debugfs can’t, e.g. mmap.

Sources: /proc/version

Its data is shared with uname(), which is a POSIX C function and has a Linux syscall to back it up.

Where the data comes from and how to modify it:

In this repo, leaking host information, and to make builds more reproducible, we are setting:

  • user and date to dummy values

  • hostname to the kernel git commit

So the file contains something like:

Linux version 4.19.0-dirty (lkmc@84df9525b0c27f3ebc2ebb1864fa62a97fdedb7d) (gcc version 6.4.0 (Buildroot 2018.05-00002-gbc60382b8f)) #1 SMP Thu Jan 1 00:00:00 UTC 1970

15.8.3. sysfs

Sysfs is more restricted than procfs, as it does not take an arbitrary file_operations:

echo $?

Outcome: the test passes:



Vs procfs:

You basically can only do open, close, read, write, and lseek on sysfs files.

It is similar to a seq_file file operation, except that write is also implemented.

TODO: what are those kobject structs? Make a more complex example that shows what they can do.


15.8.4. Character devices

Character devices can have arbitrary File operations associated to them:

echo $?

Outcome: the test passes:



Unlike procfs entires, character device files are created with userland mknod or mknodat syscalls:

mknod </dev/path_to_dev> c <major> <minor>

Intuitively, for physical devices like keyboards, the major number maps to which driver, and the minor number maps to which device it is.

A single driver can drive multiple compatible devices.

The major and minor numbers can be observed with:

ls -l /dev/urandom


crw-rw-rw-    1 root     root        1,   9 Jun 29 05:45 /dev/urandom

which means:

  • c (first letter): this is a character device. Would be b for a block device.

  • 1, 9: the major number is 1, and the minor 9

To avoid device number conflicts when registering the driver we:

  • ask the kernel to allocate a free major number for us with: register_chrdev(0

  • find ouf which number was assigned by grepping /proc/devices for the kernel module name

15.9. Pseudo files

15.9.1. File operations

File operations are the main method of userland driver communication. struct file_operations determines what the kernel will do on filesystem system calls of Pseudo filesystems.

This example illustrates the most basic system calls: open, read, write, close and lseek:

echo $?

Outcome: the test passes:



Then give this a try:

sh -x /

We have put printks on each fop, so this allows you to see which system calls are being made for each command.

15.9.2. seq_file

Writing trivial read File operations is repetitive and error prone. The seq_file API makes the process much easier for those trivial cases:

echo $?

Outcome: the test passes:



In this example we create a debugfs file that behaves just like a file that contains:


However, we only store a single integer in memory and calculate the file on the fly in an iterator fashion.

Bibliography: seq_file single_open

If you have the entire read output upfront, single_open is an even more convenient version of seq_file:

echo $?

Outcome: the test passes:



This example produces a debugfs file that behaves like a file that contains:


15.9.3. poll

The poll system call allows an user process to do a non-busy wait on a kernel event:


Outcome: jiffies gets printed to stdout every second from userland.


Typically, we are waiting for some hardware to make some piece of data available available to the kernel.

The hardware notifies the kernel that the data is ready with an interrupt.

To simplify this example, we just fake the hardware interrupts with a kthread that sleeps for a second in an infinite loop.

15.9.4. ioctl

The ioctl system call is the best way to pass an arbitrary number of parameters to the kernel in a single go:

echo $?

Outcome: the test passes:



ioctl is one of the most important methods of communication with real device drivers, which often take several fields as input.

ioctl takes as input:

  • an integer request : it usually identifies what type of operation we want to do on this call

  • an untyped pointer to memory: can be anything, but is typically a pointer to a struct

    The type of the struct often depends on the request input

    This struct is defined on a uapi-style C header that is used both to compile the kernel module and the userland executable.

    The fields of this struct can be thought of as arbitrary input parameters.

And the output is:

  • an integer return value. man ioctl documents:

    Usually, on success zero is returned. A few ioctl() requests use the return value as an output parameter and return a nonnegative value on success. On error, -1 is returned, and errno is set appropriately.

  • the input pointer data may be overwritten to contain arbitrary output


15.9.5. mmap

The mmap system call allows us to share memory between user and kernel space without copying:

echo $?

Outcome: the test passes:



In this example, we make a tiny 4 byte kernel buffer available to user-space, and we then modify it on userspace, and check that the kernel can see the modification.

mmap, like most more complex File operations, does not work with debugfs as of 4.9, so we use a procfs file for it.


15.9.6. Anonymous inode

Anonymous inodes allow getting multiple file descriptors from a single filesystem entry, which reduces namespace pollution compared to creating multiple device files:

echo $?

Outcome: the test passes:



This example gets an anonymous inode via ioctl from a debugfs entry by using anon_inode_getfd.

Reads to that inode return the sequence: 1, 10, 100, …​ 10000000, 1, 100, …​

Netlink sockets offer a socket API for kernel / userland communication:

echo $?

Outcome: the test passes:



Launch multiple user requests in parallel to stress our socket:

insmod /netlink.ko sleep=1
for i in `seq 16`; do /netlink.out & done


15.10. kthread

Kernel threads are managed exactly like userland threads; they also have a backing task_struct, and are scheduled with the same mechanism:

insmod /kthread.ko

Outcome: dmesg counts from 0 to 9 once every second infinitely many times:


The count stops when we rmmod:

rmmod kthread

The sleep is done with usleep_range, see: sleep.


15.10.1. kthreads

Let’s launch two threads and see if they actually run in parallel:

insmod /kthreads.ko

Outcome: two threads count to dmesg from 0 to 9 in parallel.

Each line has output of form:

<thread_id> <count>

Possible very likely outcome:

1 0
2 0
1 1
2 1
1 2
2 2
1 3
2 3

The threads almost always interleaved nicely, thus confirming that they are actually running in parallel.

15.10.2. sleep

Count to dmesg every one second from 0 up to n - 1:

insmod /sleep.ko n=5

The sleep is done with a call to usleep_range directly inside module_init for simplicity.


15.10.3. Workqueues

A more convenient front-end for kthread:

insmod /workqueue_cheat.ko

Outcome: count from 0 to 9 infinitely many times

Stop counting:

rmmod workqueue_cheat

The workqueue thread is killed after the worker function returns.

We can’t call the module just workqueue.c because there is already a built-in with that name: Workqueue from workqueue

Count from 0 to 9 every second infinitely many times by scheduling a new work item from a work item:

insmod /work_from_work.ko


rmmod work_from_work

The sleep is done indirectly through: queue_delayed_work, which waits the specified time before scheduling the work.

15.10.4. schedule

Let’s block the entire kernel! Yay:

./run --eval-after 'dmesg -n 1;insmod /schedule.ko schedule=0'

Outcome: the system hangs, the only way out is to kill the VM.

kthreads only allow interrupting if you call schedule(), and the schedule=0 kernel module parameter turns it off.

Sleep functions like usleep_range also end up calling schedule.

If we allow schedule() to be called, then the system becomes responsive:

./run --eval-after 'dmesg -n 1;insmod /schedule.ko schedule=1'

and we can observe the counting with:

dmesg -w

The system also responds if we add another core:

./run --cpus 2 --eval-after 'dmesg -n 1;insmod /schedule.ko schedule=0'

15.10.5. Wait queues

Wait queues are a way to make a thread sleep until an event happens on the queue:

insmod /wait_queue.c

Dmesg output:

0 0
1 0
2 0
# Wait one second.
0 1
1 1
2 1
# Wait one second.
0 2
1 2
2 2

Stop the count:

rmmod wait_queue

This example launches three threads:

  • one thread generates events every with wake_up

  • the other two threads wait for that with wait_event, and print a dmesg when it happens.

    The wait_event macro works a bit like:

    while (!cond)

15.11. Timers

Count from 0 to 9 infinitely many times in 1 second intervals using timers:

insmod /timer.ko

Stop counting:

rmmod timer

Timers are callbacks that run when an interrupt happens, from the interrupt context itself.

Therefore they produce more accurate timing than thread scheduling, which is more complex, but you can’t do too much work inside of them.


15.12. IRQ

15.12.1. irq.ko

Brute force monitor every shared interrupt that will accept us:

./run --eval-after 'insmod /irq.ko' --graphic

Now try the following:

  • press a keyboard key and then release it after a few seconds

  • press a mouse key, and release it after a few seconds

  • move the mouse around

Outcome: dmesg shows which IRQ was fired for each action through messages of type:

handler irq = 1 dev = 250

dev is the character device for the module and never changes, as can be confirmed by:

grep lkmc_irq /proc/devices

The IRQs that we observe are:

  • 1 for keyboard press and release.

    If you hold the key down for a while, it starts firing at a constant rate. So this happens at the hardware level!

  • 12 mouse actions

This only works if for IRQs for which the other handlers are registered as IRQF_SHARED.

We can see which ones are those, either via dmesg messages of type:

genirq: Flags mismatch irq 0. 00000080 (myirqhandler0) vs. 00015a00 (timer)
request_irq irq = 0 ret = -16
request_irq irq = 1 ret = 0

which indicate that 0 is not, but 1 is, or with:

cat /proc/interrupts

which shows:

  0:         31   IO-APIC   2-edge      timer
  1:          9   IO-APIC   1-edge      i8042, myirqhandler0

so only 1 has myirqhandler0 attached but not 0.

The QEMU monitor also has some interrupt statistics for x86_64:

./qemu-monitor info irq

TODO: properly understand how each IRQ maps to what number.

15.12.2. dummy-irq

The Linux kernel v4.16 mainline also has a dummy-irq module at drivers/misc/dummy-irq.c for monitoring a single IRQ.

We build it by default with:


And then you can do

./run --graphic

and in guest:

modprobe dummy-irq irq=1

Outcome: when you click a key on the keyboard, dmesg shows:

dummy-irq: interrupt occurred on IRQ 1

However, this module is intended to fire only once as can be seen from its source:

    static int count = 0;

    if (count == 0) {
        printk(KERN_INFO "dummy-irq: interrupt occurred on IRQ %d\n",

and furthermore interrupt 1 and 12 happen immediately TODO why, were they somehow pending?

So so see something interesting, you need to monitor an interrupt that is more rare than the keyboard, e.g. platform_device.

15.12.3. /proc/interrupts

In the guest with QEMU graphic mode:

watch -n 1 cat /proc/interrupts

Then see how clicking the mouse and keyboard affect the interrupt counts.

This confirms that:

  • 1: keyboard

  • 12: mouse click and drags

The module also shows which handlers are registered for each IRQ, as we have observed at irq.ko

When in text mode, we can also observe interrupt line 4 with handler ttyS0 increase continuously as IO goes through the UART.

15.13. Kernel utility functions

15.13.2. virt_to_phys

Convert a virtual address to physical:

insmod /virt_to_phys.ko
cat /sys/kernel/debug/lkmc_virt_to_phys

Sample output:

*kmalloc_ptr = 0x12345678
kmalloc_ptr = ffff88000e169ae8
virt_to_phys(kmalloc_ptr) = 0xe169ae8
static_var = 0x12345678
&static_var = ffffffffc0002308
virt_to_phys(&static_var) = 0x40002308

We can confirm that the kmalloc_ptr translation worked with:

./qemu-monitor 'xp 0xe169ae8'

which reads four bytes from a given physical address, and gives the expected:

000000000e169ae8: 0x12345678

TODO it only works for kmalloc however, for the static variable:

./qemu-monitor 'xp 0x40002308'

it gave a wrong value of 00000000.

Bibliography: Userland physical address experiments

Only tested in x86_64.

The Linux kernel exposes physical addresses to userland through:

  • /proc/<pid>/maps

  • /proc/<pid>/pagemap

  • /dev/mem

In this section we will play with them.

First get a virtual address to play with:

/virt_to_phys_test.out &

Sample output:

vaddr 0x600800
pid 110

The program:

  • allocates a volatile variable and sets is value to 0x12345678

  • prints the virtual address of the variable, and the program PID

  • runs a while loop until until the value of the variable gets mysteriously changed somehow, e.g. by nasty tinkerers like us

Then, translate the virtual address to physical using /proc/<pid>/maps and /proc/<pid>/pagemap:

/virt_to_phys_user.out 110 0x600800

Sample output physical address:


Now we can verify that virt_to_phys_user.out gave the correct physical address in the following ways:

Bibliography: QEMU xp

The xp QEMU monitor command reads memory at a given physical address.

First launch virt_to_phys_user.out as described at Userland physical address experiments.

On a second terminal, use QEMU to read the physical address:

./qemu-monitor 'xp 0x7c7b800'


0000000007c7b800: 0x12345678

Yes!!! We read the correct value from the physical address.

We could not find however to write to memory from the QEMU monitor, boring. /dev/mem

/dev/mem exposes access to physical addresses, and we use it through the convenient devmem BusyBox utility.

First launch virt_to_phys_user.out as described at Userland physical address experiments.

Next, read from the physical address:

devmem 0x7c7b800

Possible output:

Memory mapped at address 0x7ff7dbe01000.
Value at address 0X7C7B800 (0x7ff7dbe01800): 0x12345678

which shows that the physical memory contains the expected value 0x12345678.

0x7ff7dbe01000 is a new virtual address that devmem maps to the physical address to be able to read from it.

Modify the physical memory:

devmem 0x7c7b800 w 0x9abcdef0

After one second, we see on the screen:

i 9abcdef0
[1]+  Done                       /virt_to_phys_test.out

so the value changed, and the while loop exited!

This example requires:

  • CONFIG_STRICT_DEVMEM=n, otherwise devmem fails with:

    devmem: mmap: Operation not permitted
  • nopat kernel parameter

which we set by default. pagemap_dump.out

Dump the physical address of all pages mapped to a given process using /proc/<pid>/maps and /proc/<pid>/pagemap.

First launch virt_to_phys_user.out as described at Userland physical address experiments. Suppose that the output was:

# /virt_to_phys_test.out &
vaddr 0x601048
pid 63
# /virt_to_phys_user.out 63 0x601048

Now obtain the page map for the process:

/pagemap_dump.out 63

Sample output excerpt:

vaddr pfn soft-dirty file/shared swapped present library
400000 1ede 0 1 0 1 /virt_to_phys_test.out
600000 1a6f 0 0 0 1 /virt_to_phys_test.out
601000 1a61 0 0 0 1 /virt_to_phys_test.out
602000 2208 0 0 0 1 [heap]
603000 220b 0 0 0 1 [heap]
7ffff78ec000 1fd4 0 1 0 1 /lib/

Meaning of the flags:

  • vaddr: first virtual address of a page the belongs to the process. Notably:

    ./run-toolchain readelf -- -l "$(./getvar userland_build_dir)/virt_to_phys_test.out"


      Type           Offset             VirtAddr           PhysAddr
                     FileSiz            MemSiz              Flags  Align
      LOAD           0x0000000000000000 0x0000000000400000 0x0000000000400000
                     0x000000000000075c 0x000000000000075c  R E    0x200000
      LOAD           0x0000000000000e98 0x0000000000600e98 0x0000000000600e98
                     0x00000000000001b4 0x0000000000000218  RW     0x200000
     Section to Segment mapping:
      Segment Sections...
       02     .interp .hash .dynsym .dynstr .rela.plt .init .plt .text .fini .rodata .eh_frame_hdr .eh_frame
       03     .ctors .dtors .jcr .dynamic .got.plt .data .bss

    from which we deduce that:

    • 400000 is the text segment

    • 600000 is the data segment

  • pfn: add three zeroes to it, and you have the physical address.

    Three zeroes is 12 bits which is 4kB, which is the size of a page.

    For example, the virtual address 0x601000 has pfn of 0x1a61, which means that its physical address is 0x1a61000

    This is consistent with what virt_to_phys_user.out told us: the virtual address 0x601048 has physical address 0x1a61048.

    048 corresponds to the three last zeroes, and is the offset within the page.

    Also, this value falls inside 0x601000, which as previously analyzed is the data section, which is the normal location for global variables such as ours.

  • soft-dirty: TODO

  • file/shared: TODO. 1 seems to indicate that the page can be shared across processes, possibly for read-only pages? E.g. the text segment has 1, but the data has 0.

  • swapped: TODO swapped to disk?

  • present: TODO vs swapped?

  • library: which executable owns that page

This program works in two steps:

  • parse the human readable lines lines from /proc/<pid>/maps. This files contains lines of form:

    7ffff7b6d000-7ffff7bdd000 r-xp 00000000 fe:00 658                        /lib/

    which tells us that:

    • 7f8af99f8000-7f8af99ff000 is a virtual address range that belong to the process, possibly containing multiple pages.

    • /lib/ is the name of the library that owns that memory

  • loop over each page of each address range, and ask /proc/<pid>/pagemap for more information about that page, including the physical address

15.14. Linux kernel tracing

Good overviews:

I hope to have examples of all methods some day, since I’m obsessed with visibility.


Logs proc events such as process creation to a netlink socket.

We then have a userland program that listens to the events and prints them out:

# /proc_events.out &
# set mcast listen ok
# sleep 2 & sleep 1
fork: parent tid=48 pid=48 -> child tid=79 pid=79
fork: parent tid=48 pid=48 -> child tid=80 pid=80
exec: tid=80 pid=80
exec: tid=79 pid=79
# exit: tid=80 pid=80 exit_code=0
exit: tid=79 pid=79 exit_code=0
echo a

TODO: why exit: tid=79 shows after exit: tid=80?

Note how echo a is a Bash built-in, and therefore does not spawn a new process.

TODO: why does this produce no output?

/proc_events.out >f &

TODO can you get process data such as UID and process arguments? It seems not since exec_proc_event contains so little data: We could try to immediately read it from /proc, but there is a risk that the process finished and another one took its PID, so it wouldn’t be reliable. CONFIG_PROC_EVENTS aarch64

0111ca406bdfa6fd65a2605d353583b4c4051781 was failing with:

>>> kernel_modules 1.0 Building
/usr/bin/make -j8 -C '/linux-kernel-module-cheat//out/aarch64/buildroot/build/kernel_modules-1.0/user' BR2_PACKAGE_OPENBLAS="" CC="/linux-kernel-module-cheat//out/aarch64/buildroot/host/bin/aarch64-buildroot-linux-uclibc-gcc" LD="/linux-kernel-module-cheat//out/aarch64/buildroot/host/bin/aarch64-buildroot-linux-uclibc-ld"
/linux-kernel-module-cheat//out/aarch64/buildroot/host/bin/aarch64-buildroot-linux-uclibc-gcc  -ggdb3 -fopenmp -O0 -std=c99 -Wall -Werror -Wextra -o 'proc_events.out' 'proc_events.c'
In file included from /linux-kernel-module-cheat//out/aarch64/buildroot/host/aarch64-buildroot-linux-uclibc/sysroot/usr/include/signal.h:329:0,
                 from proc_events.c:12:
/linux-kernel-module-cheat//out/aarch64/buildroot/host/aarch64-buildroot-linux-uclibc/sysroot/usr/include/sys/ucontext.h:50:16: error: field ‘uc_mcontext’ has incomplete type
     mcontext_t uc_mcontext;

so we commented it out.

Related threads:

If we try to naively update uclibc to 1.0.29 with buildroot_override, which contains the above mentioned patch, clean aarch64 test build fails with:

../utils/ldd.c: In function 'elf_find_dynamic':
../utils/ldd.c:238:12: warning: cast to pointer from integer of different size [-Wint-to-pointer-cast]
     return (void *)byteswap_to_host(dynp->d_un.d_val);
/tmp/user/20321/cciGScKB.o: In function `process_line_callback':
msgmerge.c:(.text+0x22): undefined reference to `escape'
/tmp/user/20321/cciGScKB.o: In function `process':
msgmerge.c:(.text+0xf6): undefined reference to `poparser_init'
msgmerge.c:(.text+0x11e): undefined reference to `poparser_feed_line'
msgmerge.c:(.text+0x128): undefined reference to `poparser_finish'
collect2: error: ld returned 1 exit status recipe for target '../utils/' failed
make[2]: *** [../utils/] Error 1
make[2]: *** Waiting for unfinished jobs....
/tmp/user/20321/ccF8V8jF.o: In function `process':
msgfmt.c:(.text+0xbf3): undefined reference to `poparser_init'
msgfmt.c:(.text+0xc1f): undefined reference to `poparser_feed_line'
msgfmt.c:(.text+0xc2b): undefined reference to `poparser_finish'
collect2: error: ld returned 1 exit status recipe for target '../utils/' failed
make[2]: *** [../utils/] Error 1
package/ recipe for target '/data/git/linux-kernel-module-cheat/out/aarch64/buildroot/build/uclibc-custom/.stamp_built' failed
make[1]: *** [/data/git/linux-kernel-module-cheat/out/aarch64/buildroot/build/uclibc-custom/.stamp_built] Error 2
Makefile:79: recipe for target '_all' failed
make: *** [_all] Error 2

Buildroot master has already moved to uclibc 1.0.29 at f8546e836784c17aa26970f6345db9d515411700, but it is not yet in any tag…​ so I’m not tempted to update it yet just for this.

15.14.2. ftrace

Trace a single function:

cd /sys/kernel/debug/tracing/

# Stop tracing.
echo 0 > tracing_on

# Clear previous trace.
echo > trace

# List the available tracers, and pick one.
cat available_tracers
echo function > current_tracer

# List all functions that can be traced
# cat available_filter_functions
# Choose one.
echo __kmalloc > set_ftrace_filter
# Confirm that only __kmalloc is enabled.
cat enabled_functions

echo 1 > tracing_on

# Latest events.
head trace

# Observe trace continuously, and drain seen events out.
cat trace_pipe &

Sample output:

# tracer: function
# entries-in-buffer/entries-written: 97/97   #P:1
#                              _-----=> irqs-off
#                             / _----=> need-resched
#                            | / _---=> hardirq/softirq
#                            || / _--=> preempt-depth
#                            ||| /     delay
#           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
#              | |       |   ||||       |         |
            head-228   [000] ....   825.534637: __kmalloc <-load_elf_phdrs
            head-228   [000] ....   825.534692: __kmalloc <-load_elf_binary
            head-228   [000] ....   825.534815: __kmalloc <-load_elf_phdrs
            head-228   [000] ....   825.550917: __kmalloc <-__seq_open_private
            head-228   [000] ....   825.550953: __kmalloc <-tracing_open
            head-229   [000] ....   826.756585: __kmalloc <-load_elf_phdrs
            head-229   [000] ....   826.756627: __kmalloc <-load_elf_binary
            head-229   [000] ....   826.756719: __kmalloc <-load_elf_phdrs
            head-229   [000] ....   826.773796: __kmalloc <-__seq_open_private
            head-229   [000] ....   826.773835: __kmalloc <-tracing_open
            head-230   [000] ....   827.174988: __kmalloc <-load_elf_phdrs
            head-230   [000] ....   827.175046: __kmalloc <-load_elf_binary
            head-230   [000] ....   827.175171: __kmalloc <-load_elf_phdrs

Trace all possible functions, and draw a call graph:

echo 1 > max_graph_depth
echo 1 > events/enable
echo function_graph > current_tracer

Sample output:

# |     |   |                     |   |   |   |
 0)   2.173 us    |                  } /* ntp_tick_length */
 0)               |                  timekeeping_update() {
 0)   4.176 us    |                    ntp_get_next_leap();
 0)   5.016 us    |                    update_vsyscall();
 0)               |                    raw_notifier_call_chain() {
 0)   2.241 us    |                      notifier_call_chain();
 0) + 19.879 us   |                    }
 0)   3.144 us    |                    update_fast_timekeeper();
 0)   2.738 us    |                    update_fast_timekeeper();
 0) ! 117.147 us  |                  }
 0)               |                  _raw_spin_unlock_irqrestore() {
 0)   4.045 us    |                    _raw_write_unlock_irqrestore();
 0) + 22.066 us   |                  }
 0) ! 265.278 us  |                } /* update_wall_time */

TODO: what do + and ! mean?

Each enable under the events/ tree enables a certain set of functions, the higher the enable more functions are enabled. trace-cmd

TODO example:

./build-buildroot --config 'BR2_PACKAGE_TRACE_CMD=y'

15.14.3. Kprobes

kprobes is an instrumentation mechanism that injects arbitrary code at a given address in a trap instruction, much like GDB. Oh, the good old kernel. :-)

./build-linux --config 'CONFIG_KPROBES=y'

Then on guest:

insmod /kprobe_example.ko
sleep 4 & sleep 4 &'

Outcome: dmesg outputs on every fork:

<_do_fork> pre_handler: p->addr = 0x00000000e1360063, ip = ffffffff810531d1, flags = 0x246
<_do_fork> post_handler: p->addr = 0x00000000e1360063, flags = 0x246
<_do_fork> pre_handler: p->addr = 0x00000000e1360063, ip = ffffffff810531d1, flags = 0x246
<_do_fork> post_handler: p->addr = 0x00000000e1360063, flags = 0x246

TODO: it does not work if I try to immediately launch sleep, why?

insmod /kprobe_example.ko
sleep 4 & sleep 4 &

I don’t think your code can refer to the surrounding kernel code however: the only visible thing is the value of the registers.

You can then hack it up to read the stack and read argument values, but do you really want to?

There is also a kprobes + ftrace based mechanism with CONFIG_KPROBE_EVENTS=y which does read the memory for us based on format strings that indicate type…​ Horrendous. Used by:


15.14.4. Count boot instructions

Results (boot not excluded):

Commit Arch Simulator Instruction count







gem5 AtomicSimpleCPU




gem5 HPI








gem5 AtomicSimpleCPU



./trace-boot --arch x86_64

sample output:

instructions 1833863
entry_address 0x1000000
instructions_firmware 20708


./run --arch aarch64 --gem5 --eval 'm5 exit'
# Or:
# ./run --arch aarch64 --gem5 --eval 'm5 exit' -- --cpu-type=HPI --caches
./gem5-stat --arch aarch64 sim_insts


  • 0x1000000 is the address where QEMU puts the Linux kernel at with -kernel in x86.

    It can be found from:

    ./run-toolchain readelf -- -e "$(./getvar vmlinux)" | grep Entry

    TODO confirm further. If I try to break there with:

    ./run-gdb *0x1000000

    but I have no corresponding source line. Also note that this line is not actually the first line, since the kernel messages such as early console in extract_kernel have already shown on screen at that point. This does not break at all:

    ./run-gdb extract_kernel

    It only appears once on every log I’ve seen so far, checked with grep 0x1000000 trace.txt

    Then when we count the instructions that run before the kernel entry point, there is only about 100k instructions, which is insignificant compared to the kernel boot itself.

    TODO --arch arm and --arch aarch64 does not count firmware instructions properly because the entry point address of the ELF file (ffffff8008080000 for aarch64) does not show up on the trace at all. Tested on f8c0502bb2680f2dbe7c1f3d7958f60265347005.

  • We can also discount the instructions after init runs by using readelf to get the initial address of init. One easy way to do that now is to just run:

    ./run-gdb-user "$(./getvar userland_build_dir)/poweroff.out" main

    And get that from the traces, e.g. if the address is 4003a0, then we search:

    grep -n 4003a0 trace.txt

    I have observed a single match for that instruction, so it must be the init, and there were only 20k instructions after it, so the impact is negligible.

  • to disable networking. Is replacing init enough?

    CONFIG_NET=n did not significantly reduce instruction counts, so maybe replacing init is enough.

  • gem5 simulates memory latencies. So I think that the CPU loops idle while waiting for memory, and counts will be higher.

15.15. Linux kernel hardening

Make it harder to get hacked and easier to notice that you were, at the cost of some (small?) runtime overhead.


Detects buffer overflows for us:

./build-linux --config 'CONFIG_FORTIFY_SOURCE=y' --linux-build-id fortify
./build-modules --clean
./run --eval-after 'insmod /strlen_overflow.ko' --linux-build-id fortify

Possible dmesg output:

strlen_overflow: loading out-of-tree module taints kernel.
detected buffer overflow in strlen
------------[ cut here ]------------

followed by a trace.

You may not get this error because this depends on strlen overflowing at least until the next page: if a random \0 appears soon enough, it won’t blow up as desired.

TODO not always reproducible. Find a more reproducible failure. I could not observe it on:

insmod /memcpy_overflow.ko

15.16. User mode Linux

But in part because it is dying, I didn’t spend much effort to integrate it into this repo, although it would be a good fit in principle, since it is essentially a virtualization method.

Maybe some brave soul will send a pull request one day.

15.17. UIO

UIO is a kernel subsystem that allows to do certain types of driver operations from userland.

This would be awesome to improve debugability and safety of kernel modules.

VFIO looks like a newer and better UIO replacement, but there do not exist any examples of how to use it:

TODO get something interesting working. I currently don’t understand the behaviour very well.

TODO how to ACK interrupts? How to ensure that every interrupt gets handled separately?

TODO how to write to registers. Currently using /dev/mem and lspci.

This example should handle interrupts from userland and print a message to stdout:


TODO: what is the expected behaviour? I should have documented this when I wrote this stuff, and I’m that lazy right now that I’m in the middle of a refactor :-)

UIO interface in a nutshell:

  • blocking read / poll: waits until interrupts

  • write: call irqcontrol callback. Default: 0 or 1 to enable / disable interrupts.

  • mmap: access device memory



15.18. Linux kernel interactive stuff

15.18.1. Linux kernel console fun

Requires Graphics.

You can also try those on the Ctrl-Alt-F3 of your Ubuntu host, but it is much more fun inside a VM!

Stop the cursor from blinking:

echo 0 > /sys/class/graphics/fbcon/cursor_blink
echo 1 > /sys/class/graphics/fbcon/rotate


Documented under: Documentation/fb/.

TODO: font and keymap. Mentioned at: and I think can be done with BusyBox loadkmap and loadfont, we just have to understand their formats, related:

15.18.2. Linux kernel magic keys

Requires Graphics.

Let’s have some fun.

I think most are implemented under:


TODO find all.

Scroll up / down the terminal:


Or inside ./qemu-monitor:

sendkey shift-pgup
sendkey shift-pgdown Ctrl Alt Del

Run /sbin/reboot on guest:


Enabled from our rootfs_overlay/etc/inittab:


Linux tries to reboot, and QEMU shutdowns due to the -no-reboot option which we set by default for: Exit emulator on panic.

Under the hood, behaviour is controlled by the reboot syscall:

man 2 reboot

reboot calls can set either of the these behaviours for Ctrl-Alt-Del:

  • do a hard shutdown syscall. Set in ublibc C code with:


    or from procfs with:

    echo 1 > /proc/sys/kernel/ctrl-alt-del
  • send a SIGINT to the init process. This is what BusyBox' init does, and it then execs the string set in inittab.

    Set in uclibc C code with:


    or from procfs with:

    echo 0 > /proc/sys/kernel/ctrl-alt-del

Minimal example:

./run --kernel-cli 'init=/ctrl_alt_del.out' --graphic

When you hit Ctrl-Alt-Del in the guest, our tiny init handles a SIGINT sent by the kernel and outputs to stdout:


To map between man 2 reboot and the uclibc RB_* magic constants see:

less "$(./getvar buildroot_build_build_dir)"/uclibc-*/include/sys/reboot.h"

The procfs mechanism is documented at:

less linux/Documentation/sysctl/kernel.txt

which says:

When the value in this file is 0, ctrl-alt-del is trapped and
sent to the init(1) program to handle a graceful restart.
When, however, the value is > 0, Linux's reaction to a Vulcan
Nerve Pinch (tm) will be an immediate reboot, without even
syncing its dirty buffers.

Note: when a program (like dosemu) has the keyboard in 'raw'
mode, the ctrl-alt-del is intercepted by the program before it
ever reaches the kernel tty layer, and it's up to the program
to decide what to do with it.

Bibliography: SysRq

We cannot test these actual shortcuts on QEMU since the host captures them at a lower level, but from:


we can for example crash the system with:

sendkey alt-sysrq-c

Same but boring because no magic key:

echo c > /proc/sysrq-trigger

Implemented in:


On your host, on modern systems that don’t have the SysRq key you can do:


which prints a message to dmesg of type:

sysrq: SysRq : HELP : loglevel(0-9) reboot(b) crash(c) terminate-all-tasks(e) memory-full-oom-kill(f) kill-all-tasks(i) thaw-filesystems(j) sak(k) show-backtrace-all-active-cpus(l) show-memory-usage(m) nice-all-RT-tasks(n) poweroff(o) show-registers(p) show-all-timers(q) unraw(r) sync(s) show-task-states(t) unmount(u) show-blocked-tasks(w) dump-ftrace-buffer(z)

Individual SysRq can be enabled or disabled with the bitmask:


The bitmask is documented at:

less linux/Documentation/admin-guide/sysrq.rst

15.18.3. TTY

In order to play with TTYs, do this:

printf '
tty2::respawn:/sbin/getty -n -L -l / tty2 0 vt100
tty4::respawn:/sbin/getty 0 tty4
::respawn:/sbin/getty -L ttyS0 0 vt100
::respawn:/sbin/getty -L ttyS1 0 vt100
::respawn:/sbin/getty -L ttyS2 0 vt100
# Leave one serial empty.
#::respawn:/sbin/getty -L ttyS3 0 vt100
' >> rootfs_overlay/etc/inittab
./run --graphic -- \
  -serial telnet::1235,server,nowait \
  -serial vc:800x600 \
  -serial telnet::1236,server,nowait \

and on a second shell:

telnet localhost 1235

We don’t add more TTYs by default because it would spawn more processes, even if we use askfirst instead of respawn.

On the GUI, switch TTYs with:

You can also test this on most hosts such as Ubuntu 18.04, except that when in the GUI, you must use Ctrl-Alt-Fx to switch to another terminal.

Next, we also have the following shells running on the serial ports, hit enter to activate them:

although we cannot change between terminals from there.

Each populated TTY contains a "shell":

Identify the current TTY with the command:



This outputs:

Get the TTY in bulk for all processes:


The TTY appears under the TT section, which is enabled by -o tty. This shows the TTY device number, e.g.:


and we can then confirm it with:

ls -l /dev/tty1

Next try:

insmod /kthread.ko

and switch between virtual terminals, to understand that the dmesg goes to whatever current virtual terminal you are on, but not the others, and not to the serial terminals.

Bibliography: Start a getty from outside of init

TODO: how to place an sh directly on a TTY as well without getty?

If I try the exact same command that the inittab is doing from a regular shell after boot:

/sbin/getty 0 tty1

it fails with:

getty: setsid: Operation not permitted

The following however works:

./run --eval 'getty 0 tty1 & getty 0 tty2 & getty 0 tty3 & sleep 99999999' --graphic

presumably because it is being called from init directly?

Outcome: Alt-Right cycles between three TTYs, tty1 being the default one that appears under the boot messages.

man 2 setsid says that there is only one failure possibility:

EPERM The process group ID of any process equals the PID of the calling process. Thus, in particular, setsid() fails if the calling process is already a process group leader.

We can get some visibility into it to try and solve the problem with:

/ console kernel boot parameter

Take the command described at TTY and try adding the following:

  • -e 'console=tty7': boot messages still show on /dev/tty1 (TODO how to change that?), but we don’t get a shell at the end of boot there.

    Instead, the shell appears on /dev/tty7.

  • -e 'console=tty2' like /dev/tty7, but /dev/tty2 is broken, because we have two shells there:

    • one due to the ::respawn:-/bin/sh entry which uses whatever console points to

    • another one due to the tty2::respawn:/sbin/getty entry we added

  • -e 'console=ttyS0' much like tty2, but messages show only on serial, and the terminal is broken due to having multiple shells on it

  • -e 'console=tty1 console=ttyS0': boot messages show on both tty1 and ttyS0, but only S0 gets a shell because it came last

This is due to the CONFIG_LOGO=y option which we enable by default.

reset on the terminal then kills the poor penguins.

When CONFIG_LOGO=y is set, the logo can be disabled at boot with:

./run --kernel-cli 'logo.nologo'

Looks like a recompile is needed to modify the image…​

15.19. DRM

DRM / DRI is the new interface that supersedes fbdev:

./build-buildroot --config 'BR2_PACKAGE_LIBDRM=y'
./build-userland --has-package libdrm -- libdrm_modeset
./run --eval-after '/libdrm_modeset.out' --graphic

Outcome: for a few seconds, the screen that contains the terminal gets taken over by changing colors of the rainbow.

TODO not working for aarch64, it takes over the screen for a few seconds and the kernel messages disappear, but the screen stays black all the time.

./build-buildroot --config 'BR2_PACKAGE_LIBDRM=y'
./build-userland --has-package libdrm
./run --eval-after '/libdrm_modeset.out' --graphic

kmscube however worked, which means that it must be a bug with this demo?

We set CONFIG_DRM=y on our default kernel configuration, and it creates one device file for each display:

# ls -l /dev/dri
total 0
crw-------    1 root     root      226,   0 May 28 09:41 card0
# grep 226 /proc/devices
226 drm
# ls /sys/module/drm /sys/module/drm_kms_helper/

Try creating new displays:

./run --arch aarch64 --graphic -- -device virtio-gpu-pci

to see multiple /dev/dri/cardN, and then use a different display with:

./run --eval-after '/libdrm_modeset.out' --graphic


15.19.1. kmscube

./build-buildroot --config-fragment buildroot_config/kmscube

Outcome: a colored spinning cube coded in OpenGL + EGL takes over your display and spins forever:

It is a bit amusing to see OpenGL running outside of a window manager window like that:

TODO: it is very slow, about 1FPS. I tried Buildroot master ad684c20d146b220dd04a85dbf2533c69ec8ee52 with:

make qemu_x86_64_defconfig
printf "
" >> .config

and the FPS was much better, I estimate something like 15FPS.

On Ubuntu 18.04 with NVIDIA proprietary drivers:

sudo apt-get instll kmscube

fails with:

drmModeGetResources failed: Invalid argument
failed to initialize legacy DRM

15.19.2. kmscon

TODO get working.

Implements a console for DRM.

The Linux kernel has a built-in fbdev console: fbcon but not for DRM it seems.

The upstream project seems dead with last commit in 2014:

Build failed in Ubuntu 18.04 with: but this fork compiled but didn’t run on host:

Haven’t tested the fork on QEMU too much insanity.

15.19.3. libdri2

TODO get working.

Looks like a more raw alternative to libdrm:

./build-buildroot --config 'BR2_PACKABE_LIBDRI2=y'
wget \
  -O "$(./getvar userland_src_dir)/dri2test.c" \ \

but then I noticed that that example requires multiple files, and I don’t feel like integrating it into our build.

When I build it on Ubuntu 18.04 host, it does not generate any executable, so I’m confused.

15.20. Linux kernel testing

15.20.1. LTP

Linux Test Project

C userland test suite.

Buildroot already has a package, so it is trivial to build it:

./build-buildroot --config 'BR2_PACKAGE_LTP_TESTSUITE=y'

Then try it out with:

cd /usr/lib/ltp-testsuite/testcases

There is a main executable execltp to run everything, but it depends on Python, so let’s just run them manually.

TODO a large chunk of tests, the Open POSIX test suite, is disabled with a comment on Buildroot master saying build failed: However, both tickets mentioned there were closed, so we should try it out and patch Buildroot if it works now.

15.20.2. stress

POSIX userland stress. Two versions:

./build-buildroot --config 'BR2_PACKAGE_STRESS=y'
./build-buildroot --config 'BR2_PACKAGE_STRESS_NG=y'


Likely the NG one is best, but it requires BR2_TOOLCHAIN_USES_GLIBC=y which we don’t have currently because we use uclibc…​ arghhhh.

stress usage:

stress --help
stress -c 16 &

and notice how 16 threads were created in addition to a parent worker thread.

It just runs forever, so kill it when you get tired:

kill %1

stress -c 1 -t 1 makes gem5 irresponsive for a very long time.

16. Linux kernel build system

16.1. vmlinux vs bzImage vs zImage vs Image

Between all archs on QEMU and gem5 we touch all of those kernel built output files.

QEMU does not seem able to boot ELF files like vmlinux, only objdump code:

Converting arch/* images to vmlinux is possible in x86 with extract-vmlinux. But for arm it fails with:

run-detectors: unable to find an interpreter for

as mentioned at:

17. QEMU

17.1. Introduction to QEMU

QEMU is a system simulator: it simulates a CPU and devices such as interrupt handlers, timers, UART, screen, keyboard, etc.

If you are familiar with VirtualBox, then QEMU then basically does the same thing: it opens a "window" inside your desktop that can run an operating system inside your operating system.

Also both can use very similar techniques: either binary translation or KVM. VirtualBox' binary translator is / was based on QEMU’s it seems:

The huge advantage of QEMU over VirtualBox is that is supports cross arch simulation, e.g. simulate an ARM guest on an x86 host.

QEMU is likely the leading cross arch system simulator as of 2018. It is even the default Android simulator that developers get with Android Studio 3 to develop apps without real hardware.

Another advantage of QEMU over virtual box is that it doesn’t have Oracle' hands all all over it, more like RedHat + ARM.

Another advantage of QEMU is that is has no nice configuration GUI. Because who needs GUIs when you have 50 million semi-documented CLI options? Android Studio adds a custom GUI configuration tool on top of it.

QEMU is also supported by Buildroot in-tree, see e.g.: We however just build our own manually with build-qemu, as it gives more flexibility, and building QEMU is very easy!

All of this makes QEMU the natural choice of reference system simulator for this repo.

17.2. Disk persistency

We disable disk persistency for both QEMU and gem5 by default, to prevent the emulator from putting the image in an unknown state.

For QEMU, this is done by passing the snapshot option to -drive, and for gem5 it is the default behaviour.

If you hack up our run script to remove that option, then:

./run --eval-after 'date >f;poweroff'

followed by:

./run --eval-after 'cat f'

gives the date, because poweroff without -n syncs before shutdown.

The sync command also saves the disk:


When you do:


the disk image gets overwritten by a fresh filesystem and you lose all changes.

Remember that if you forcibly turn QEMU off without sync or poweroff from inside the VM, e.g. by closing the QEMU window, disk changes may not be saved.

Persistency is also turned off when booting from initrd with a CPIO instead of with a disk.

Disk persistency is useful to re-run shell commands from the history of a previous session with Ctrl-R, but we felt that the loss of determinism was not worth it.

17.2.1. gem5 disk persistency

TODO how to make gem5 disk writes persistent?

As of cadb92f2df916dbb47f428fd1ec4932a2e1f0f48 there are some read_only entries in the config.ini under cow sections, but hacking them to true did not work:

diff --git a/configs/common/ b/configs/common/
index 17498c42b..76b8b351d 100644
--- a/configs/common/
+++ b/configs/common/
@@ -60,7 +60,7 @@ os_types = { 'alpha' : [ 'linux' ],

 class CowIdeDisk(IdeDisk):
-    image = CowDiskImage(child=RawDiskImage(read_only=True),
+    image = CowDiskImage(child=RawDiskImage(read_only=False),

     def childImage(self, ci):

The directory of interest is src/dev/storage.

17.3. gem5 qcow2

qcow2 does not appear supported, there are not hits in the source tree, and there is a mention on Nate’s 2009 wishlist:

This would be good to allow storing smaller sparse ext2 images locally on disk.

17.4. Snapshot

QEMU allows us to take snapshots at any time through the monitor.

You can then restore CPU, memory and disk state back at any time.

qcow2 filesystems must be used for that to work.

To test it out, login into the VM with and run:

./run --eval-after 'umount /mnt/9p/*;/'

On another shell, take a snapshot:

./qemu-monitor savevm my_snap_id

The counting continues.

Restore the snapshot:

./qemu-monitor loadvm my_snap_id

and the counting goes back to where we saved. This shows that CPU and memory states were reverted.

The umount is needed because snapshotting conflicts with 9P, which we felt is a more valuable default. If you forget to unmount, the following error appears on the QEMU monitor:

Migration is disabled when VirtFS export path '/linux-kernel-module-cheat/out/x86_64/buildroot/build' is mounted in the guest using mount_tag 'host_out'

We can also verify that the disk state is also reversed. Guest:

echo 0 >f


./qemu-monitor savevm my_snap_id


echo 1 >f


./qemu-monitor loadvm my_snap_id


cat f

And the output is 0.

Our setup does not allow for snapshotting while using initrd.

17.4.1. Snapshot internals

Snapshots are stored inside the .qcow2 images themselves.

They can be observed with:

"$(./getvar host_dir)/bin/qemu-img" info "$(./getvar qcow2_file)"

which after savevm my_snap_id and savevm asdf contains an output of type:

image: out/x86_64/buildroot/images/rootfs.ext2.qcow2
file format: qcow2
virtual size: 512M (536870912 bytes)
disk size: 180M
cluster_size: 65536
Snapshot list:
ID        TAG                 VM SIZE                DATE       VM CLOCK
1         my_snap_id              47M 2018-04-27 21:17:50   00:00:15.251
2         asdf                    47M 2018-04-27 21:20:39   00:00:18.583
Format specific information:
    compat: 1.1
    lazy refcounts: false
    refcount bits: 16
    corrupt: false

As a consequence:

  • it is possible to restore snapshots across boots, since they stay on the same image the entire time

  • it is not possible to use snapshots with initrd in our setup, since we don’t pass -drive at all when initrd is enabled

17.5. Device models

This section documents:

For the more complex interfaces, we focus on simplified educational devices, either:

17.5.1. PCI

Only tested in x86. pci_min

PCI driver for our minimal pci_min.c QEMU fork device:

./run -- -device lkmc_pci_min


insmod /pci_min.ko



<4>[   10.608241] pci_min: loading out-of-tree module taints kernel.
<6>[   10.609935] probe
<6>[   10.651881] dev->irq = 11
lkmc_pci_min mmio_write addr = 0 val = 12345678 size = 4
<6>[   10.668515] irq_handler irq = 11 dev = 251
lkmc_pci_min mmio_write addr = 4 val = 0 size = 4

What happened:

  • right at probe time, we write to a register

  • our hardware model is coded such that it generates an interrupt when written to

  • the Linux kernel interrupt handler write to another register, which tells the hardware to stop sending interrupts

Kernel messages and printks from inside QEMU are shown all together, to see that more clearly, run in QEMU graphic mode instead.

We don’t enable the device by default because it does not work for vanilla QEMU, which we often want to test with this repository.

Probe already does a MMIO write, which generates an IRQ and tests everything. QEMU edu PCI device

Small upstream educational PCI device:


This tests a lot of features of the edu device, to understand the results, compare the inputs with the documentation of the hardware:


Works because we add to our default QEMU CLI:

-device edu

This example uses:

  • the QEMU edu educational device, which is a minimal educational in-tree PCI example

  • out /pci.ko kernel module, which exercises the edu hardware.

    I’ve contacted the awesome original author author of edu Jiri Slaby, and he told there is no official kernel module example because this was created for a kernel module university course that he gives, and he didn’t want to give away answers. I don’t agree with that philosophy, so students, cheat away with this repo and go make startups instead.

TODO exercise DMA on the kernel module. The edu hardware model has that feature: Manipulate PCI registers directly

In this section we will try to interact with PCI devices directly from userland without kernel modules.

First identify the PCI device with:


In our case for example, we see:

00:06.0 Unclassified device [00ff]: Device 1234:11e8 (rev 10)
00:07.0 Unclassified device [00ff]: Device 1234:11e9

which we identify as being edu and pci_min respectively by the magic numbers: 1234:11e?

Alternatively, we can also do use the QEMU monitor:

./qemu-monitor info qtree

which gives:

      dev: lkmc_pci_min, id ""
        addr = 07.0
        romfile = ""
        rombar = 1 (0x1)
        multifunction = false
        command_serr_enable = true
        x-pcie-lnksta-dllla = true
        x-pcie-extcap-init = true
        class Class 00ff, addr 00:07.0, pci id 1234:11e9 (sub 1af4:1100)
        bar 0: mem at 0xfeb54000 [0xfeb54007]
      dev: edu, id ""
        addr = 06.0
        romfile = ""
        rombar = 1 (0x1)
        multifunction = false
        command_serr_enable = true
        x-pcie-lnksta-dllla = true
        x-pcie-extcap-init = true
        class Class 00ff, addr 00:06.0, pci id 1234:11e8 (sub 1af4:1100)
        bar 0: mem at 0xfea00000 [0xfeafffff]

Read the configuration registers as binary:

hexdump /sys/bus/pci/devices/0000:00:06.0/config

Get nice human readable names and offsets of the registers and some enums:

setpci --dumpregs

Get the values of a given config register from its human readable name, either with either bus or device id:

setpci -s 0000:00:06.0 BASE_ADDRESS_0
setpci -d 1234:11e9 BASE_ADDRESS_0

Note however that BASE_ADDRESS_0 also appears when you do:

lspci -v


Memory at feb54000

Then you can try messing with that address with /dev/mem:

devmem 0xfeb54000 w 0x12345678

which writes to the first register of our pci_min device.

The device then fires an interrupt at irq 11, which is unhandled, which leads the kernel to say you are a bad boy:

lkmc_pci_min mmio_write addr = 0 val = 12345678 size = 4
<5>[ 1064.042435] random: crng init done
<3>[ 1065.567742] irq 11: nobody cared (try booting with the "irqpoll" option)

followed by a trace.

Next, also try using our irq.ko IRQ monitoring module before triggering the interrupt:

insmod /irq.ko
devmem 0xfeb54000 w 0x12345678

Our kernel module handles the interrupt, but does not acknowledge it like our proper pci_min kernel module, and so it keeps firing, which leads to infinitely many messages being printed:

handler irq = 11 dev = 251 pciutils

There are two versions of setpci and lspci:

  • a simple one from BusyBox

  • a more complete one from pciutils which Buildroot has a package for, and is the default on Ubuntu 18.04 host. This is the one we enable by default. Introduction to PCI

The PCI standard is non-free, obviously like everything in low level: but Google gives several illegal PDF hits :-)

And of course, the best documentation available is:

Like every other hardware, we could interact with PCI on x86 using only IO instructions and memory operations.

But PCI is a complex communication protocol that the Linux kernel implements beautifully for us, so let’s use the kernel API.

Bibliography: PCI BFD

lspci -k shows something like:

00:04.0 Class 00ff: 1234:11e8 lkmc_pci

Meaning of the first numbers:


Often abbreviated to BDF.

Sometimes a fourth number is also added, e.g.:


TODO is that the domain?

Class: pure magic: TODO: does it have any side effects? Set in the edu device at:


Each PCI device has 6 BAR IOs (base address register) as per the PCI spec.

Each BAR corresponds to an address range that can be used to communicate with the PCI.

Each BAR is of one of the two types:

  • IORESOURCE_IO: must be accessed with inX and outX

  • IORESOURCE_MEM: must be accessed with ioreadX and iowriteX. This is the saner method apparently, and what the edu device uses.

The length of each region is defined by the hardware, and communicated to software via the configuration registers.

The Linux kernel automatically parses the 64 bytes of standardized configuration registers for us.

QEMU devices register those regions with:

memory_region_init_io(&edu->mmio, OBJECT(edu), &edu_mmio_ops, edu,
                "edu-mmio", 1 << 20);
pci_register_bar(pdev, 0, PCI_BASE_ADDRESS_SPACE_MEMORY, &edu->mmio);

17.5.2. GPIO

TODO: broken. Was working before we moved arm from -M versatilepb to -M virt around af210a76711b7fa4554dcc2abd0ddacfc810dfd4. Either make it work on -M virt if that is possible, or document precisely how to make it work with versatilepb, or hopefully vexpress which is newer.

The best you can do is to hack our build script to add:


where PL061 is the dominating ARM Holdings hardware that handles GPIO.

Then compile with:

./build-buildroot --arch arm --config-fragment buildroot_config/gpio
./build-linux --config-fragment linux_config/gpio

then test it out with:


Buildroot’s Linux tools package provides some GPIO CLI tools: lsgpio, gpio-event-mon, gpio-hammer, TODO document them here.

17.5.3. LEDs

TODO: broken when arm moved to -M virt, same as GPIO.

Hack QEMU’s hw/misc/arm_sysctl.c with a printf:

static void arm_sysctl_write(void *opaque, hwaddr offset,
                            uint64_t val, unsigned size)
    arm_sysctl_state *s = (arm_sysctl_state *)opaque;

    switch (offset) {
    case 0x08: /* LED */
        printf("LED val = %llx\n", (unsigned long long)val);

and then rebuild with:

./build-qemu --arch arm
./build-linux --arch arm --config-fragment linux_config/leds

But beware that one of the LEDs has a heartbeat trigger by default (specified on dts), so it will produce a lot of output.

And then activate it with:

cd /sys/class/leds/versatile:0
cat max_brightness
echo 255 >brightness

Relevant QEMU files:

  • hw/arm/versatilepb.c

  • hw/misc/arm_sysctl.c

Relevant kernel files:

  • arch/arm/boot/dts/versatile-pb.dts

  • drivers/leds/led-class.c

  • drivers/leds/leds-sysctl.c

17.5.4. platform_device

Minimal platform device example coded into the -M versatilepb SoC of our QEMU fork.

Using this device now requires checking out to the branch:

git checkout platform-device
git submodule sync

before building, it does not work on master.

Rationale: we found out that the kernels that build for qemu -M versatilepb don’t work on gem5 because versatilepb is an old pre-v7 platform, and gem5 requires armv7. So we migrated over to -M virt to have a single kernel for both gem5 and QEMU, and broke this since the single kernel was more important. TODO port to -M virt.


Expected outcome after insmod:

  • QEMU reports MMIO with printfs

  • IRQs are generated and handled by this module, which logs to dmesg

Without insmoding this module, try writing to the register with /dev/mem:

devmem 0x101e9000 w 0x12345678

We can also observe the interrupt with dummy-irq:

modprobe dummy-irq irq=34
insmod /platform_device.ko

The IRQ number 34 was found by on the dmesg after:

insmod /platform_device.ko

17.6. QEMU monitor

The QEMU monitor is a terminal that allows you to send text commands to the QEMU VM:

On another terminal, run:


or send one command such as info qtree and quit the monitor:

./qemu-monitor info qtree

or equivalently:

echo 'info qtree' | ./qemu-monitor

Source: qemu-monitor

qemu-monitor uses the -monitor QEMU command line option, which makes the monitor listen from a socket.

Alternatively, from text mode:

Ctrl-A C

and go back to the terminal with:

Ctrl-A C

And in graphic mode from the GUI:

Ctrl-Alt ?

where ? is a digit 1, or 2, or, 3, etc. depending on what else is available on the GUI: serial, parallel and frame buffer.

In general, ./qemu-monitor is the best option, as it:

  • works on both modes

  • allows to use the host Bash history to re-run one off commands

  • allows you to search the output of commands on your host shell even when in graphic mode

Getting everything to work required careful choice of QEMU command line options:

17.6.1. QEMU monitor from guest

It is also worth looking into the QEMU Guest Agent tool qemu-gq that can be enabled with:

./build-buildroot --config 'BR2_PACKAGE_QEMU=y'

17.6.2. QEMU monitor from GDB

When doing GDB step debug it is possible to send QEMU monitor commands through the GDB monitor command, which saves you the trouble of opening yet another shell.

Try for example:

monitor help
monitor info qtree

17.7. Debug the emulator

When you start hacking QEMU or gem5, it is useful to see what is going on inside the emulator themselves.

This is of course trivial since they are just regular userland programs on the host, but we make it a bit easier with:

./run --debug-vm

Then you could:

break edu_mmio_read

And in QEMU:


Or for a faster development loop:

./run --debug-vm='-ex "break edu_mmio_read" -ex "run"'

When in QEMU text mode, using --debug-vm makes Ctrl-C not get passed to the QEMU guest anymore: it is instead captured by GDB itself, so allow breaking. So e.g. you won’t be able to easily quit from a guest program like:

sleep 10

In graphic mode, make sure that you never click inside the QEMU graphic while debugging, otherwise you mouse gets captured forever, and the only solution I can find is to go to a TTY with Ctrl-Alt-F1 and kill QEMU.

You can still send key presses to QEMU however even without the mouse capture, just either click on the title bar, or alt tab to give it focus.

17.7.1. Debug gem5 Python scripts

Start pdb at the first instruction:

./run --gem5 --gem5-exe-args='--pdb' --terminal

Requires --terminal as we must be on foreground.

Alternatively, you can add to the point of the code where you want to break the usual:

import ipdb; ipdb.set_trace()

and then run with:

./run --gem5 --terminal

17.8. Tracing

QEMU can log several different events.

The most interesting are events which show instructions that QEMU ran, for which we have a helper:

./trace-boot --arch x86_64

Under the hood, this uses QEMU’s -trace option.

You can then inspect the address of each instruction run:

less "$(./getvar --arch x86_64 run_dir)/trace.txt"

Sample output excerpt:

exec_tb 0.000 pid=10692 tb=0x7fb4f8000040 pc=0xfffffff0
exec_tb 35.391 pid=10692 tb=0x7fb4f8000180 pc=0xfe05b
exec_tb 21.047 pid=10692 tb=0x7fb4f8000340 pc=0xfe066
exec_tb 12.197 pid=10692 tb=0x7fb4f8000480 pc=0xfe06a

Get the list of available trace events:

./run --trace help

TODO: any way to show the actualy disassembled instruction executed directly from there? Possible with QEMU -d tracing.

Enable other specific trace events:

./run --trace trace1,trace2
./qemu-trace2txt -a "$arch"
less "$(./getvar -a "$arch" run_dir)/trace.txt"

This functionality relies on the following setup:

  • ./configure --enable-trace-backends=simple. This logs in a binary format to the trace file.

    It makes 3x execution faster than the default trace backend which logs human readable data to stdout.

    Logging with the default backend log greatly slows down the CPU, and in particular leads to this boot message:

    All QSes seen, last rcu_sched kthread activity 5252 (4294901421-4294896169), jiffies_till_next_fqs=1, root ->qsmask 0x0
    swapper/0       R  running task        0     1      0 0x00000008
     ffff880007c03ef8 ffffffff8107aa5d ffff880007c16b40 ffffffff81a3b100
     ffff880007c03f60 ffffffff810a41d1 0000000000000000 0000000007c03f20
     fffffffffffffedc 0000000000000004 fffffffffffffedc ffffffff00000000
    Call Trace:
     <IRQ>  [<ffffffff8107aa5d>] sched_show_task+0xcd/0x130
     [<ffffffff810a41d1>] rcu_check_callbacks+0x871/0x880
     [<ffffffff810a799f>] update_process_times+0x2f/0x60

    in which the boot appears to hang for a considerable time.

  • patch QEMU source to remove the disable from exec_tb in the trace-events file. See also:

17.8.1. QEMU -d tracing

QEMU also has a second trace mechanism in addition to -trace, find out the events with:

./run -- -d help

Let’s pick the one that dumps executed instructions, in_asm:

./run --eval '/poweroff.out' -- -D out/trace.txt -d in_asm
less out/trace.txt

Sample output excerpt:

0xfffffff0:  ea 5b e0 00 f0           ljmpw    $0xf000:$0xe05b

0x000fe05b:  2e 66 83 3e 88 61 00     cmpl     $0, %cs:0x6188
0x000fe062:  0f 85 7b f0              jne      0xd0e1

TODO: after IN:, symbol names are meant to show, which is awesome, but I don’t get any. I do see them however when running a bare metal example from:

TODO: what is the point of having two mechanisms, -trace and -d? -d tracing is cool because it does not require a messy recompile, and it can also show symbols.

17.8.2. QEMU trace register values

TODO: is it possible to show the register values for each instruction?

This would include the memory values read into the registers.

Seems impossible due to optimizations that QEMU does:

PANDA can list memory addresses, so I bet it can also decode the instructions: I wonder why they don’t just upstream those things to QEMU’s tracing:

gem5 can do it: gem5 tracing.

17.8.3. Trace source lines

We can further use Binutils' addr2line to get the line that corresponds to each address:

./trace-boot --arch x86_64
./trace2line --arch x86_64
less "$(./getvar --arch x86_64 run_dir)/trace-lines.txt"

The format is as follows:

39368 _static_cpu_has arch/x86/include/asm/cpufeature.h:148


  • 39368: number of consecutive times that a line ran. Makes the output much shorter and more meaningful

  • _static_cpu_has: name of the function that contains the line

  • arch/x86/include/asm/cpufeature.h:148: file and line

This could of course all be done with GDB, but it would likely be too slow to be practical.

TODO do even more awesome offline post-mortem analysis things, such as:

  • detect if we are in userspace or kernelspace. Should be a simple matter of reading the

  • read kernel data structures, and determine the current thread. Maybe we can reuse / extend the kernel’s GDB Python scripts??

17.8.4. QEMU record and replay

QEMU runs, unlike gem5, are not deterministic by default, however it does support a record and replay mechanism that allows you to replay a previous run deterministically.

This awesome feature allows you to examine a single run as many times as you would like until you understand everything:

# Record a run.
./run --eval-after '/rand_check.out;/poweroff.out;' --record
# Replay the run.
./run --eval-after '/rand_check.out;/poweroff.out;' --replay

A convenient shortcut to do both at once to test the feature is:

./qemu-rr --eval-after '/rand_check.out;/poweroff.out;'

By comparing the terminal output of both runs, we can see that they are the exact same, including things which normally differ across runs:

The record and replay feature was revived around QEMU v3.0.0. It existed earlier but it rot completely. As of v3.0.0 it is still flaky: sometimes we get deadlocks, and only a limited number of command line arguments are supported.

TODO: using -r as above leads to a kernel warning:

rcu_sched detected stalls on CPUs/tasks

TODO: replay deadlocks intermittently at disk operations, last kernel message:

EXT4-fs (sda): re-mounted. Opts: block_validity,barrier,user_xattr

TODO replay with network gets stuck:

./qemu-rr --eval-after 'ifup -a;wget -S;/poweroff.out;'

after the message:

adding dns

There is explicit network support on the QEMU patches, but either it is buggy or we are not using the correct magic options.

Solved on unmerged c42634d8e3428cfa60672c3ba89cabefc720cde9 from

TODO arm and aarch64 only seem to work with initrd since I cannot plug a working IDE disk device? See also:

Then, when I tried with initrd and no disk:

./build-buildroot --arch aarch64 --initrd
./qemu-rr --arch aarch64 --eval-after '/rand_check.out;/poweroff.out;' --initrd

QEMU crashes with:

ERROR:replay/replay-time.c:49:replay_read_clock: assertion failed: (replay_file && replay_mutex_locked())

I had the same error previously on x86-64, but it was fixed: so maybe the forgot to fix it for aarch64?

Solved on unmerged c42634d8e3428cfa60672c3ba89cabefc720cde9 from QEMU reverse debugging

TODO get working.

QEMU replays support checkpointing, and this allows for a simplistic "reverse debugging" implementation proposed at on the unmerged

./run --eval-after '/rand_check.out;/poweroff.out;' --record
./run --eval-after '/rand_check.out;/poweroff.out;' --replay --wait-gdb

On another shell:

./run-gdb start_kernel



and we are back at start_kernel

17.8.5. QEMU trace multicore

TODO: is there any way to distinguish which instruction runs on each core? Doing:

./run --arch x86_64 --cpus 2 --eval '/poweroff.out' --trace exec_tb

just appears to output both cores intertwined without any clear differentiation.

17.8.6. gem5 tracing

gem5 provides also provides a tracing mechanism documented at:

./run --arch aarch64 --eval 'm5 exit' --gem5 --trace Exec
less "$(./getvar --arch aarch64 run_dir)/trace.txt"

Output the trace to stdout instead of a file:

./run --arch aarch64 --eval 'm5 exit' --gem5 --trace Exec --trace-stdout

This would produce a lot of output however, so you will likely not want that when tracing a Linux kernel boot instructions. But it can be very convenient for smaller traces.

List all available debug flags:

./run --arch aarch64 --gem5-exe-args='--debug-help' --gem5

but to understand most of them you have to look at the source code:

less "$(./getvar gem5_src_dir)/src/cpu/SConscript"
less "$(./getvar gem5_src_dir)/src/cpu/"

The traces are generated from DPRINTF(<trace-id> calls scattered throughout the code.

As can be seen on the Sconstruct, Exec is just an alias that enables a set of flags.

Be warned, the trace is humongous, at 16Gb.

We can make the trace smaller by naming the trace file as trace.txt.gz, which enables GZIP compression, but that is not currently exposed on our scripts, since you usually just need something human readable to work on.

Enabling tracing made the runtime about 4x slower on the P51, with or without .gz compression.

The output format is of type:

25007000: system.cpu T0 : @start_kernel    : stp
25007000: system.cpu T0 : @start_kernel.0  :   addxi_uop   ureg0, sp, #-112 : IntAlu :  D=0xffffff8008913f90
25007500: system.cpu T0 : @start_kernel.1  :   strxi_uop   x29, [ureg0] : MemWrite :  D=0x0000000000000000 A=0xffffff8008913f90
25008000: system.cpu T0 : @start_kernel.2  :   strxi_uop   x30, [ureg0, #8] : MemWrite :  D=0x0000000000000000 A=0xffffff8008913f98
25008500: system.cpu T0 : @start_kernel.3  :   addxi_uop   sp, ureg0, #0 : IntAlu :  D=0xffffff8008913f90

There are two types of lines:


  • 25007500: time count in some unit. Note how the microops execute at further timestamps.

  • system.cpu: distinguishes between CPUs when there are more than one

  • T0: thread number. TODO: hyperthread? How to play with it?

  • @start_kernel: we are in the start_kernel function. Awesome feature! Implemented with libelf copy pasted in-tree ext/libelf. To get raw addresses, remove the ExecSymbol, which is enabled by Exec. This can be done with Exec,-ExecSymbol.

  • .1 as in @start_kernel.1: index of the microop

  • stp: instruction disassembly. Seems to use .isa files dispersed per arch, which is an in house format:

  • strxi_uop x29, [ureg0]: microop disassembly.

  • MemWrite : D=0x0000000000000000 A=0xffffff8008913f90: a memory write microop:

    • D stands for data, and represents the value that was written to memory or to a register

    • A stands for address, and represents the address to which the value was written. It only shows when data is being written to memory, but not to registers.

The best way to verify all of this is to write some baremetal code

Trace the source lines just like for QEMU with:

./trace-boot --arch aarch64 --gem5
./trace2line --arch aarch64 --gem5
less "$(./getvar --arch aarch64 run_dir)/trace-lines.txt"

TODO: 7452d399290c9c1fc6366cdad129ef442f323564 ./trace2line this is too slow and takes hours. QEMU’s processing of 170k events takes 7 seconds. gem5’s processing is analogous, but there are 140M events, so it should take 7000 seconds ~ 2 hours which seems consistent with what I observe, so maybe there is no way to speed this up…​ The workaround is to just use gem5’s ExecSymbol to get function granularity, and then GDB individually if line detail is needed?

17.9. QEMU GUI is unresponsive

Sometimes in Ubuntu 14.04, after the QEMU SDL GUI starts, it does not get updated after keyboard strokes, and there are artifacts like disappearing text.

We have not managed to track this problem down yet, but the following workaround always works:


This started happening when we switched to building QEMU through Buildroot, and has not been observed on later Ubuntu.

Using text mode is another workaround if you don’t need GUI features.

18. gem5

Getting started at: gem5 Buildroot setup.

18.1. gem5 vs QEMU

  • advantages of gem5:

  • disadvantage of gem5: slower than QEMU, see: Benchmark Linux kernel boot

    This implies that the user base is much smaller, since no Android devs.

    Instead, we have only chip makers, who keep everything that really works closed, and researchers, who can’t version track or document code properly >:-) And this implies that:

    • the documentation is more scarce

    • it takes longer to support new hardware features

    Well, not that AOSP is that much better anyways.

  • not sure: gem5 has BSD license while QEMU has GPL

    This suits chip makers that want to distribute forks with secret IP to their customers.

    On the other hand, the chip makers tend to upstream less, and the project becomes more crappy in average :-)

18.2. gem5 run benchmark

OK, this is why we used gem5 in the first place, performance measurements!

Let’s see how many cycles Dhrystone, which Buildroot provides, takes for a few different input parameters.

First build Dhrystone into the root filesystem:

./build-buildroot --config 'BR2_PACKAGE_DHRYSTONE=y'

Then, a flexible setup is demonstrated at:

cat out/gem5-bench-dhrystone.txt

Sample output:

n cycles
1000 12898577
10000 23441629
100000 128428617

so as expected, the Dhrystone run with a larger input parameter 100000 took more cycles than the ones with smaller input parameters.

The gem5-stats commands output the approximate number of CPU cycles it took Dhrystone to run.

Another interesting example can be found at: gem5-bench-cache.

A more naive and simpler to understand approach would be a direct:

./run --arch aarch64 --gem5 --eval 'm5 checkpoint;m5 resetstats;dhrystone 10000;m5 exit'

but the problem is that this method does not allow to easily run a different script without running the boot again, see: gem5 checkpoint restore and run a different script.

Now you can play a fun little game with your friends:

  • pick a computational problem

  • make a program that solves the computation problem, and outputs output to stdout

  • write the code that runs the correct computation in the smallest number of cycles possible

To find out why your program is slow, a good first step is to have a look at stats.txt file.

18.2.1. Skip extra benchmark instructions

A few imperfections of our benchmarking method are:

  • when we do m5 resetstats and m5 exit, there is some time passed before the exec system call returns and the actual benchmark starts and ends

  • the benchmark outputs to stdout, which means so extra cycles in addition to the actual computation. But TODO: how to get the output to check that it is correct without such IO cycles?

Solutions to these problems include:

  • modify benchmark code with instrumentation directly, see m5ops instructions for an example.

  • monitor known addresses TODO possible? Create an example.

Those problems should be insignificant if the benchmark runs for long enough however.

18.2.2. gem5 system parameters

Besides optimizing a program for a given CPU setup, chip developers can also do the inverse, and optimize the chip for a given benchmark!

The rabbit hole is likely deep, but let’s scratch a bit of the surface. Number of cores
./run --arch arm --cpus 2 --gem5

Check with:

cat /proc/cpuinfo
getconf _NPROCESSORS_CONF gem5 arm more than 8 cores

Build the kernel with the gem5 arm Linux kernel patches, and then run:

./run \
  --arch aarch64 \
  --linux-build-id gem5-v4.15 \
  --gem5 \
  --cpus 16 \
  -- \
  --param 'system.realview.gic.gem5_extensions = True' \
; gem5 cache size

A quick ./run --gem5 -- -h leads us to the options:


But keep in mind that it only affects benchmark performance of the most detailed CPU types:

arch CPU type caches used













*: couldn’t test because of:

Cache sizes can in theory be checked with the methods described at:

getconf -a | grep CACHE
cat /sys/devices/system/cpu/cpu0/cache/index2/size

but for some reason the Linux kernel is not seeing the cache sizes:

Behaviour breakdown:

  • arm QEMU and gem5 (both AtomicSimpleCPU or HPI), x86 gem5: /sys files don’t exist, and getconf and lscpu value empty

  • x86 QEMU: /sys files exist, but getconf and lscpu values still empty

So we take a performance measurement approach instead:

./gem5-bench-cache --arch aarch64
cat "$(./getvar --arch aarch64 run_dir)/bench-cache.txt"

which gives:

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 1000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024   --l1i_size=1024   --l2_size=1024   --l3_size=1024   --cpu-type=HPI --restore-with-cpu=HPI
time 23.82
exit_status 0
cycles 93284622
instructions 4393457

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 1000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024kB --l1i_size=1024kB --l2_size=1024kB --l3_size=1024kB --cpu-type=HPI --restore-with-cpu=HPI
time 14.91
exit_status 0
cycles 10128985
instructions 4211458

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 10000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024   --l1i_size=1024   --l2_size=1024   --l3_size=1024   --cpu-type=HPI --restore-with-cpu=HPI
time 51.87
exit_status 0
cycles 188803630
instructions 12401336

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 10000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024kB --l1i_size=1024kB --l2_size=1024kB --l3_size=1024kB --cpu-type=HPI --restore-with-cpu=HPI
time 35.35
exit_status 0
cycles 20715757
instructions 12192527

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 100000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024   --l1i_size=1024   --l2_size=1024   --l3_size=1024   --cpu-type=HPI --restore-with-cpu=HPI
time 339.07
exit_status 0
cycles 1176559936
instructions 94222791

cmd ./run --gem5 --arch aarch64 --gem5-readfile "dhrystone 100000" --gem5-restore 1 -- --caches --l2cache --l1d_size=1024kB --l1i_size=1024kB --l2_size=1024kB --l3_size=1024kB --cpu-type=HPI --restore-with-cpu=HPI
time 240.37
exit_status 0
cycles 125666679
instructions 91738770

We make the following conclusions:

  • the number of instructions almost does not change: the CPU is waiting for memory all the extra time. TODO: why does it change at all?

  • the wall clock execution time is not directionally proportional to the number of cycles: here we had a 10x cycle increase, but only 2x time increase. This suggests that the simulation of cycles in which the CPU is waiting for memory to come back is faster. gem5 memory latency

TODO These look promising:


TODO: now to verify this with the Linux kernel? Besides raw performance benchmarks. Memory size
./run --arch arm --memory 512M

and verify inside the guest with:

free -m gem5 disk and network latency

TODO These look promising:

--ethernet-linkdelay gem5 clock frequency

Clock frequency: TODO how does it affect performance in benchmarks?

./run --arch aarch64 --gem5 -- --cpu-clock 10000000

Check with:

m5 resetstats
sleep 10
m5 dumpstats

and then:

./gem5-stat --arch aarch64

TODO: why doesn’t this exist:

ls /sys/devices/system/cpu/cpu0/cpufreq

18.2.3. Interesting benchmarks

Buildroot built-in libraries, mostly under Libraries > Other:

  • Armadillo C++: linear algebra

  • fftw: Fourier transform

  • Flann

  • GSL: various

  • liblinear

  • libspacialindex

  • libtommath

  • qhull

There are not yet enabled, but it should be easy to so, see: Add new Buildroot packages BST vs heap


./run \
  --arch aarch64 \
  --eval-after '/' \
  --gem5 \
  --gem5-readfile '/bst_vs_heap.out' \
./bst-vs-heap --arch aarch64 --gem5 > bst_vs_heap.dat

Sources: OpenMP

Implemented by GCC itself, so just a toolchain configuration, no external libs, and we enable it by default:

/openmp.out BLAS

Buildroot supports it, which makes everything just trivial:

./build-buildroot --config 'BR2_PACKAGE_OPENBLAS=y'
./build-userland --has-package openblas -- openblas_hello
./run --eval-after '/openblas_hello.out; echo $?'

Outcome: the test passes:


The test performs a general matrix multiplication:

    |  1.0 -3.0 |   |  1.0  2.0  1.0 |       |  0.5  0.5  0.5 |   |  11.0 - 9.0  5.0 |
1 * |  2.0  4.0 | * | -3.0  4.0 -1.0 | + 2 * |  0.5  0.5  0.5 | = | - 9.0  21.0 -1.0 |
    |  1.0 -1.0 |                            |  0.5  0.5  0.5 |   |   5.0 - 1.0  3.0 |

This can be deduced from the Fortran interfaces at

less "$(./getvar buildroot_build_build_dir)"/openblas-*/reference/dgemmf.f

which we can map to our call as:

C := alpha*op( A )*op( B ) + beta*C,
cblas_dgemm(      CblasColMajor, CblasNoTrans, CblasTrans,3,3,2  ,1,    A,3,  B,3,  2   ,C,3  ); Eigen

Header only linear algebra library with a mainline Buildroot package:

./build-buildroot --config 'BR2_PACKAGE_EIGEN=y'
./build-userland --has-package eigen -- eigen_hello

Just create an array and print it:

./run --eval-after '/eigen_hello.out'


  3  -1
2.5 1.5

This example just creates a matrix and prints it out. PARSEC benchmark

We have ported parts of the PARSEC benchmark for cross compilation at: See the documentation on that repo to find out which benchmarks have been ported. Some of the benchmarks were are segfaulting, they are documented in that repo.

There are two ways to run PARSEC with this repo: PARSEC benchmark without parsecmgmt
./build --arch arm --download-dependencies gem5-buildroot parsec-benchmark
./build-buildroot --arch arm --config 'BR2_PACKAGE_PARSEC_BENCHMARK=y'
./run --arch arm --gem5

Once inside the guest, launch one of the test input sized benchmarks manually as in:

cd /parsec/ext/splash2x/apps/fmm/run
../inst/arm-linux.gcc/bin/fmm 1 < input_1

To find run out how to run many of the benchmarks, have a look at the script of the parse-benchmark repo.

From the guest, you can also run it as:

cd /parsec

but this might be a bit time consuming in gem5. PARSEC change the input size

Running a benchmark of a size different than test, e.g. simsmall, requires a rebuild with:

./build-buildroot \
  --arch arm \
  -- parsec_benchmark-reconfigure \

Large input may also require tweaking: only contains the run commands for the test size, and cannot be used for simsmall.

The easiest thing to do, is to scroll up on the host shell after the build, and look for a line of type:

Running /root/linux-kernel-module-cheat/out/aarch64/buildroot/build/parsec-benchmark-custom/ext/splash2x/apps/ocean_ncp/inst/aarch64-linux.gcc/bin/ocean_ncp -n2050 -p1 -e1e-07 -r20000 -t28800

and then tweak the command found in accordingly.

Yes, we do run the benchmarks on host just to unpack / generate inputs. They are expected fail to run since they were build for the guest instead of host, including for x86_64 guest which has a different interpreter than the host’s (see file myexecutable).

The rebuild is required because we unpack input files on the host.

Separating input sizes also allows to create smaller images when only running the smaller benchmarks.

This limitation exists because parsecmgmt generates the input files just before running via the Bash scripts, but we can’t run parsecmgmt on gem5 as it is too slow!

One option would be to do that inside the guest with QEMU.

Also, we can’t generate all input sizes at once, because many of them have the same name and would overwrite one another…​

PARSEC simply wasn’t designed with non native machines in mind…​ PARSEC benchmark with parsecmgmt

Most users won’t want to use this method because:

  • running the parsecmgmt Bash scripts takes forever before it ever starts running the actual benchmarks on gem5

    Running on QEMU is feasible, but not the main use case, since QEMU cannot be used for performance measurements

  • it requires putting the full .tar inputs on the guest, which makes the image twice as large (1x for the .tar, 1x for the unpacked input files)

It would be awesome if it were possible to use this method, since this is what Parsec supports officially, and so:

  • you don’t have to dig into what raw command to run

  • there is an easy way to run all the benchmarks in one go to test them out

  • you can just run any of the benchmarks that you want

but it simply is not feasible in gem5 because it takes too long.

If you still want to run this, try it out with:

./build-buildroot \
  --arch aarch64 \
  --config 'BR2_TARGET_ROOTFS_EXT2_SIZE="3G"' \
  -- parsec_benchmark-reconfigure \

And then you can run it just as you would on the host:

cd /parsec/
parsecmgmt -a run -p splash2x.fmm -i test PARSEC uninstall

If you want to remove PARSEC later, Buildroot doesn’t provide an automated package removal mechanism: Remove Buildroot packages, but the following procedure should be satisfactory:

rm -rf \
  "$(./getvar buildroot_download_dir)"/parsec-* \
  "$(./getvar buildroot_build_dir)"/build/parsec-* \
  "$(./getvar buildroot_build_dir)"/build/packages-file-list.txt \
  "$(./getvar buildroot_build_dir)"/images/rootfs.* \
  "$(./getvar buildroot_build_dir)"/target/parsec-* \
./build-buildroot --arch arm PARSEC benchmark hacking

If you end up going inside submodules/parsec-benchmark to hack up the benchmark (you will!), these tips will be helpful.

Buildroot was not designed to deal with large images, and currently cross rebuilds are a bit slow, due to some image generation and validation steps.

A few workarounds are:

  • develop in host first as much as you can. Our PARSEC fork supports it.

    If you do this, don’t forget to do a:

    cd "$(./getvar parsec_src_dir)"
    git clean -xdf .

    before going for the cross compile build.

  • patch Buildroot to work well, and keep cross compiling all the way. This should be totally viable, and we should do it.

    Don’t forget to explicitly rebuild PARSEC with:

    ./build-buildroot \
      --arch arm \
      --config 'BR2_PACKAGE_PARSEC_BENCHMARK=y' \
      -- parsec_benchmark-reconfigure \

    You may also want to test if your patches are still functionally correct inside of QEMU first, which is a faster emulator.

  • sell your soul, and compile natively inside the guest. We won’t do this, not only because it is evil, but also because Buildroot explicitly does not support it: ARM employees have been known to do this:

18.3. gem5 kernel command line parameters

Analogous to QEMU:

./run --arch arm --kernel-cli 'init=/poweroff.out' --gem5

Internals: when we give --command-line= to gem5, it overrides default command lines, including some mandatory ones which are required to boot properly.

Our run script hardcodes the require options in the default --command-line and appends extra options given by -e.

To find the default options in the first place, we removed --command-line and ran:

./run --arch arm --gem5

and then looked at the line of the Linux kernel that starts with:

Kernel command line:

18.4. gem5 GDB step debug

18.4.1. gem5 GDB step debug kernel

Analogous to QEMU, on the first shell:

./run --arch arm --wait-gdb --gem5

On the second shell:

./run-gdb --arch arm --gem5

On a third shell:


When you want to break, just do a Ctrl-C on GDB shell, and then continue.

And we now see the boot messages, and then get a shell. Now try the / procedure described for QEMU: GDB step debug kernel post-boot. gem5 GDB step debug kernel aarch64

TODO: GDB fails with:

Reading symbols from vmlinux...done.
Remote debugging using localhost:7000
Remote 'g' packet reply is too long: 000000000000000090a4f90fc0ffffff4875450ec0ffffff01000000000000000100000000000000000000000000000001000000000000000000000000000000ffffffffffffffff646d60616b64fffe7f7f7f7f7f7f7f7f0101010101010101300000000000000000000000ffffffff48454422207d2c2017162f21262820160100000000000000070000000000000001000000000000004075450ec0ffffffc073450ec0ffffff82080000000000004075450ec0ffffff8060f90fc0ffffffc073450ec0fffffff040900880ffffff40ab400ec0ffffff586d900880ffffff0068a20ec0ffffff903b010880ffffffc8ff210880ffffff903b010880ffffffccff210880ffffff050000200000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000

and gem5 says:

4107766500: system.remote_gdb: remote gdb attached
warn: Couldn't read data from debugger.
4107767500: system.remote_gdb: remote gdb detached
-ex 'set tdesc filename out/aarch64/buildroot/build/gdb-7.11.1/./gdb/features/aarch64.xml'

but it did not help.

18.4.2. gem5 GDB step debug userland process

We are unable to use gdbserver because of networking: gem5 host to guest networking

The alternative is to do as in GDB step debug userland processes.

First make sure that for your arch the kernel debugging on the given target works for the architecture: gem5 GDB step debug, on which we rely. When we last tested, this was not the case for aarch64: gem5 GDB step debug kernel aarch64

Next, follow the exact same steps explained at gdb-step-debug-userland-non-init-without&.adoc, but passing -g to every command as usual.

But then TODO (I’ll still go crazy one of those days): for arm, while debugging /myinsmod.out /hello.ko, after then line:

23     if (argc < 3) {
24         params = "";

I press n, it just runs the program until the end, instead of stopping on the next line of execution. The module does get inserted normally.


./run-gdb-user --arch arm --gem5 gem5-1.0/gem5/util/m5/m5 main

breaks when m5 is run on guest, but does not show the source code.

18.5. gem5 checkpoint

Analogous to QEMU’s Snapshot, but better since it can be started from inside the guest, so we can easily checkpoint after a specific guest event, e.g. just before init is done.

./run --arch arm --gem5

In the guest, wait for the boot to end and run:

m5 checkpoint

where m5 is a guest utility present inside the gem5 tree which we cross-compiled and installed into the guest.

To restore the checkpoint, kill the VM and run:

./run --arch arm --gem5 --gem5-restore 1

The --gem5-restore option restores the checkpoint that was created most recently.

Let’s create a second checkpoint to see how it works, in guest:

date >f
m5 checkpoint

Kill the VM, and try it out:

./run --arch arm --gem5 --gem5-restore 1

Here we use --gem5-restore 1 again, since the second snapshot we took is now the most recent one

Now in the guest:

cat f

contains the date. The file f wouldn’t exist had we used the first checkpoint with --gem5-restore 2, which is the second most recent snapshot taken.

If you automate things with Kernel command line parameters as in:

./run --arch arm --eval 'm5 checkpoint;m5 resetstats;dhrystone 1000;m5 exit' --gem5

Then there is no need to pass the kernel command line again to gem5 for replay:

./run --arch arm --gem5 --gem5-restore 1

since boot has already happened, and the parameters are already in the RAM of the snapshot.

18.5.1. gem5 checkpoint internals

Checkpoints are stored inside the m5out directory at:

"$(./getvar --gem5 m5out_dir)/cpt.<checkpoint-time>"

where <checkpoint-time> is the cycle number at which the checkpoint was taken. exposes the -r N flag to restore checkpoints, which N-th checkpoint with the largest <checkpoint-time>:

However, that interface is bad because if you had taken previous checkpoints, you have no idea what N to use, unless you memorize which checkpoint was taken at which cycle.

Therefore, just use our superior --gem5-restore flag, which uses directory timestamps to determine which checkpoint you created most recently.

The -r N integer value is just pure sugar, the backend at m5.instantiate just takes the actual tracepoint directory path as input.

18.5.2. gem5 checkpoint restore and run a different script

You want to automate running several tests from a single pristine post-boot state.

The problem is that boot takes forever, and after the checkpoint, the memory and disk states are fixed, so you can’t for example:

  • hack up an existing rc script, since the disk is fixed

  • inject new kernel boot command line options, since those have already been put into memory by the bootloader

There is however a few loopholes, m5 readfile being the simplest, as it reads whatever is present on the host.

So we can do it like:

# Boot, checkpoint and exit.
printf 'echo "setup run";m5 exit' > "$(./getvar gem5_readfile)"
./run --gem5 --eval 'm5 checkpoint;m5 readfile >;sh'

# Restore and run the first benchmark.
printf 'echo "first benchmark";m5 exit' > "$(./getvar gem5_readfile)"
./run --gem5 --gem5-restore 1

# Restore and run the second benchmark.
printf 'echo "second benchmark";m5 exit' > "$(./getvar gem5_readfile)"
./run --gem5 --gem5-restore 1

# If something weird happened, create an interactive shell to examine the system.
printf 'sh' > "$(./getvar gem5_readfile)"
./run --gem5 --gem5-restore 1

Since this is such a common setup, we provide some helpers for it as described at gem5 run benchmark:

Other loophole possibilities include:

18.5.3. gem5 restore checkpoint with a different CPU

gem5 can switch to a different CPU model when restoring a checkpoint.

A common combo is to boot Linux with a fast CPU, make a checkpoint and then replay the benchmark of interest with a slower CPU.

An illustrative interactive run:

./run --arch arm --gem5

In guest:

m5 checkpoint

And then restore the checkpoint with a different CPU:

./run --arch arm --gem5 --gem5-restore 1 -- --caches --restore-with-cpu=HPI

18.6. Pass extra options to gem5

Pass options to the script:

  • get help:

    ./run --gem5 -- -h
  • boot with the more detailed and slow HPI CPU model:

    ./run --arch arm --gem5 -- --caches --cpu-type=HPI

Pass options to the gem5 executable itself:

  • get help:

    ./run --gem5-exe-args='-h' --gem5

18.7. gem5 exit after a number of instructions

Quit the simulation after 1024 instructions:

./run --gem5 -- -I 1024

Can be nicely checked with gem5 tracing.

Cycles instead of instructions:

./run --gem5 -- --memory 1024

Otherwise the simulation runs forever by default.

18.8. m5ops

m5ops are magic instructions which lead gem5 to do magic things, like quitting or dumping stats.


There are two main ways to use m5ops:

m5 is convenient if you only want to take snapshots before or after the benchmark, without altering its source code. It uses the m5ops instructions as its backend.

m5 cannot should / should not be used however:

  • in bare metal setups

  • when you want to call the instructions from inside interest points of your benchmark. Otherwise you add the syscall overhead to the benchmark, which is more intrusive and might affect results.

    Why not just hardcode some m5ops instructions as in our example instead, since you are going to modify the source of the benchmark anyways?

18.8.1. m5

m5 is a guest command line utility that is installed and run on the guest, that serves as a CLI front-end for the m5ops

It is possible to guess what most tools do from the corresponding m5ops, but let’s at least document the less obvious ones here. m5 exit

End the simulation.

Sane Python scripts will exit gem5 with status 0, which is what does. m5 fail

End the simulation with a failure exit event:

m5 fail 1

Sane Python scripts would use that as the exit status of gem5, which would be useful for testing purposes, but at 200281b08ca21f0d2678e23063f088960d3c0819 just prints an error message:

Simulated exit code not 0! Exit code is 1

and exits with status 0.

TODO: it used to exit non 0, be like that, but it actually got changed to just print the message. Why?

m5 fail is just a superset of m5 exit, which is just:

m5 fail 0 m5 writefile

Send a guest file to the host. 9P is a more advanced alternative.


echo mycontent > myfileguest
m5 writefile myfileguest myfilehost


cat "$(./getvar --arch aarch64 --gem5 m5out_dir)/myfilehost"

Does not work for subdirectories, gem5 crashes:

m5 writefile myfileguest mydirhost/myfilehost m5 readfile

Read a host file pointed to by the --script option to stdout.


date > "$(./getvar gem5_readfile)"


m5 readfile

Outcome: date shows on guest. m5 initparam

Ermm, just another m5 readfile that only takes integers and only from CLI options? Is this software so redundant?


./run --gem5 --gem5-restore 1 -- --initparam 13
./run --gem5 --gem5-restore 1 -- --initparam 42


m5 initparm

Outputs the given paramter. m5 execfile

Trivial combination of m5 readfile + execute the script.


printf '#!/bin/sh
echo asdf
' > "$(./getvar gem5_readfile)"


touch /tmp/execfile
chmod +x /tmp/execfile
m5 execfile



18.8.2. m5ops instructions

The executable /m5ops.out illustrates how to hard code with inline assembly the m5ops that you are most likely to hack into the benchmark you are analysing:

# checkpoint
/m5ops.out c

# dumpstats
/m5ops.out d

# exit
/m5ops.out e

# dump resetstats
/m5ops.out r


That executable is of course a subset of m5 and useless by itself: its goal is only illustrate how to hardcode some m5ops yourself as one-liners.

In theory, the cleanest way to add m5ops to your benchmarks would be to do exactly what the m5 tool does:

However, I think it is usually not worth the trouble of hacking up the build system of the benchmark to do this, and I recommend just hardcoding in a few raw instructions here and there, and managing it with version control + sed. m5ops instructions interface

Let’s study how m5 uses them:

We notice that there are two different implementations for each arch:

  • magic instructions, which don’t exist in the corresponding arch

  • magic memory addresses on a given page

TODO: what is the advantage of magic memory addresses? Because you have to do more setup work by telling the kernel never to touch the magic page. For the magic instructions, the only thing that could go wrong is if you run some crazy kind of fuzzing workload that generates random instructions.

Then, in aarch64 magic instructions for example, the lines:

.macro  m5op_func, name, func, subfunc
        .globl \name
        .long 0xff000110 | (\func << 16) | (\subfunc << 12)

define a simple function function for each m5op. Here we see that:

  • 0xff000110 is a base mask for the magic non-existing instruction

  • \func and \subfunc are OR-applied on top of the base mask, and define m5op this is.

    Those values will loop over the magic constants defined in m5ops.h with the deferred preprocessor idiom.

    For example, exit is 0x21 due to:

    #define M5OP_EXIT               0x21

Finally, m5.c calls the defined functions as in:


Therefore, the runtime "argument" that gets passed to the instruction, e.g. the delay in ticks until the exit for m5 exit, gets passed directly through the aarch64 calling convention.

Keep in mind that for all archs, m5.c does the calls with 64-bit integers:

uint64_t ints[2] = {0,0};
parse_int_args(argc, argv, ints, argc);
m5_fail(ints[1], ints[0]);

Therefore, for example:

  • aarch64 uses x0 for the first argument and x1 for the second, since each is 64 bits log already

  • arm uses r0 and r1 for the first argument, and r2 and r3 for the second, since each register is only 32 bits long

That convention specifies that x0 to x7 contain the function arguments, so x0 contains the first argument, and x1 the second.

In our m5ops example, we just hardcode everything in the assembly one-liners we are producing.

We ignore the \subfunc since it is always 0 on the ops that interest us. m5op annotations

include/gem5/asm/generic/m5ops.h also describes some annotation instructions.

18.9. gem5 arm Linux kernel patches contains an ARM Linux kernel forks with a few gem5 specific Linux kernel patches on top of mainline created by ARM Holdings on top of a few upstream kernel releases.

The patches are optional: the vanilla kernel does boot. But they add some interesting gem5-specific optimizations, instrumentations and device support.

The patches also add defconfigs that are known to work well with gem5.

In order to use those patches and their associated configs, and, we recommend using Linux kernel build variants as:

git -C "$(./getvar linux_source_dir)" fetch gem5/v4.15:gem5/v4.15
git -C "$(./getvar linux_source_dir)" checkout gem5/v4.15
./build-linux \
  --arch aarch64 \
  --custom-config-file-gem5 \
  --linux-build-id gem5-v4.15 \
git -C "$(./getvar linux_source_dir)" checkout -

It is obviously not possible to understand what they actually do from their commit message, so let’s explain them one by one here as we understand them:

18.10. m5out directory

When you run gem5, it generates an m5out directory at:

echo $(./getvar --arch arm --gem5 m5out_dir)"

The location of that directory can be set with ./gem5.opt -d, and defaults to ./m5out.

The files in that directory contains some very important information about the run, and you should become familiar with every one of them.

18.10.1. system.terminal

Contains UART output, both from the Linux kernel or from the baremetal system.

Can also be seen live on m5term.

18.10.2. stats.txt

This file contains important statistics about the run:

cat "$(./getvar --arch aarch64 m5out_dir)/stats.txt"

Whenever we run m5 dumpstats or m5 exit, a section with the following format is added to that file:

---------- Begin Simulation Statistics ----------
[the stats]
---------- End Simulation Statistics   ----------

That file contains several important execution metrics, e.g. number of cycles and several types of cache misses:


18.10.3. rdtsc

Let’s have some fun and try to correlate the gem5 cycle count system.cpu.numCycles with the x86 rdtsc instruction that is supposed to do the same thing:

./build-userland -- rdtsc
./run --eval '/rdtsc.out;m5 exit;' --gem5

rdtsc outputs a cycle count which we compare with gem5’s gem5-stat:

  • 3828578153: rdtsc

  • 3830832635: gem5-stat

which gives pretty close results, and serve as a nice sanity check that the cycle counter is coherent.

It is also nice to see that rdtsc is a bit smaller than the stats.txt value, since the latter also includes the exec syscall for m5.

Bibliography: pmccntr

TODO We didn’t manage to find a working ARM analogue to rdtsc: kernel_modules/pmccntr.c is oopsing, and even it if weren’t, it likely won’t give the cycle count since boot since it needs to be activate before it starts counting anything:

18.10.4. config.ini

The config.ini file, contains a very good high level description of the system:

less $(./getvar --arch arm --gem5 m5out_dir)"

That file contains a tree representation of the system, sample excerpt:


children=cpu cpu_clk_domain

children=dstage2_mmu dtb interrupts isa istage2_mmu itb tracer


Each node has:

  • a list of child nodes, e.g. system is a child of root, and both cpu and cpu_clk_domain are children of system

  • a list of parameters, e.g. system.semihosting is Null, which means that Semihosting was turned off

    • the type parameter shows is present on every node, and it maps to a Python object that inherits from SimObject.

      For example, AtomicSimpleCPU maps is defined at src/cpu/simple/

You can also get a simplified graphical view of the tree with:

xdg-open "$(./getvar --arch arm --gem5 m5out_dir)/"

Modifying the config.ini file manually does nothing since it gets overwritten every time.

Set custom configs with the --param option of, e.g. we can make gem5 wait for GDB to connect with: --param 'system.cpu[0].wait_for_remote_gdb = True'

More complex settings involving new classes however require patching the config files, although it is easy to hack this up. See for example: patches/manual/gem5-semihost.patch.

18.11. m5term

We use the m5term in-tree executable to connect to the terminal instead of a direct telnet.

If you use telnet directly, it mostly works, but certain interactive features don’t, e.g.:

  • up and down arrows for history navigation

  • tab to complete paths

  • Ctrl-C to kill processes

TODO understand in detail what m5term does differently than telnet.

18.12. gem5 Python scripts without rebuild

We have made a crazy setup that allows you to just cd into submodules/gem5, and edit Python scripts directly there.

This is not normally possible with Buildroot, since normal Buildroot packages first copy files to the output directory ($(./getvar -a <arch> buildroot_build_build_dir)/<pkg>), and then build there.

So if you modified the Python scripts with this setup, you would still need to ./build to copy the modified files over.

For gem5 specifically however, we have hacked up the build so that we cd into the submodules/gem5 tree, and then do an out of tree build to out/common/gem5.

Another advantage of this method is the we factor out the arm and aarch64 gem5 builds which are identical and large, as well as the smaller arch generic pieces.

Using Buildroot for gem5 is still convenient because we use it to:

  • to cross build m5 for us

  • check timestamps and skip the gem5 build when it is not requested

The out of build tree is required, because otherwise Buildroot would copy the output build of all archs to each arch directory, resulting in arch^2 build copies, which is significant.

18.13. gem5 fs_bigLITTLE

By default, we use configs/example/ script.

The --gem5-script biglittle option enables the alternative configs/example/arm/ script instead.

First apply:

patch -d "$(./getvar gem5_src_dir)" -p 1 < patches/manual/gem5-biglittle.patch


./run --arch aarch64 --gem5 --gem5-script biglittle

Advantages over

  • more representative of mobile ARM SoCs, which almost always have big little cluster

  • simpler than, and therefore easier to understand and modify

Disadvantages over

  • only works for ARM, not other archs

  • not as many configuration options as, many things are hardcoded

We setup 2 big and 2 small CPUs, but cat /proc/cpuinfo shows 4 identical CPUs instead of 2 of two different types, likely because gem5 does not expose some informational register much like the caches: config.ini does show that the two big ones are DerivO3CPU and the small ones are MinorCPU.

TODO: why is the --dtb required despite having a DTB generation capability? Without it, nothing shows on terminal, and the simulation terminates with simulate() limit reached @ 18446744073709551615. The magic vmlinux.vexpress_gem5_v1.20170616 works however without a DTB.

19. Buildroot

19.1. Introduction to Buildroot

Buildroot is a set of Make scripts that download and compile from source compatible versions of:

  • GCC

  • Linux kernel

  • C standard library: Buildroot supports several implementations, we use glibc by default

  • BusyBox: provides the shell and basic command line utilities

It therefore produces a pristine, blob-less, debuggable setup, where all moving parts are configured to work perfectly together.

Perhaps the awesomeness of Buildroot only sinks in once you notice that all it takes is 4 commands as explained at

git clone
cd buildroot
git checkout 2018.02
make qemu_aarch64_virt_defconfig
make olddefconfig
time make BR2_JLEVEL="$(nproc)"
qemu-system-aarch64 -M virt -cpu cortex-a57 -nographic -smp 1 -kernel output/images/Image -append "root=/dev/vda console=ttyAMA0" -netdev user,id=eth0 -device virtio-net-device,netdev=eth0 -drive file=output/images/rootfs.ext4,if=none,format=raw,id=hd0 -device virtio-blk-device,drive=hd0

This repo basically wraps around that, and tries to make everything even more awesome for kernel developers.

The downsides of Buildroot are:

  • the first build takes a while, but it is well worth it

  • the selection of software packages is relatively limited if compared to Debian, e.g. no Java or Python package in guest out of the box.

    In theory, any software can be packaged, and the Buildroot side is easy.

    The hard part is dealing with crappy third party build systems and huge dependency chains.

19.2. Custom Buildroot configs

We provide the following mechanisms:

  • ./build-buildroot --config-fragment data/br2: append the Buildroot configuration file data/br2 to a single build. Must be passed every time you run ./build. The format is the same as buildroot_config/default.

  • ./build-buildroot --config 'BR2_SOME_OPTION="myval"': append a single option to a single build.

For example, if you decide to Enable Buildroot compiler optimizations after an initial build is finished, you must Clean the build and rebuild:

./build-buildroot \
  --config 'BR2_OPTIMIZE_3=y' \
  sample_package-dirclean \
  sample_package-reconfigure \

The clean is necessary because the source files didn’t change, so make would just check the timestamps and not build anything.

You will then likely want to make those more permanent with: Default command line arguments

19.2.1. Enable Buildroot compiler optimizations

If you are benchmarking compiled programs instead of hand written assembly, remember that we configure Buildroot to disable optimizations by default with:


to improve the debugging experience.

You will likely want to change that to:


Our kernel_modules/user package correctly forwards the Buildroot options to the build with $(TARGET_CONFIGURE_OPTS), so you don’t have to do any extra work.

Don’t forget to do that if you are adding a new package with your own build system.

Then, you have two choices:

  • if you already have a full -O0 build, you can choose to rebuild just your package of interest to save some time as described at: Custom Buildroot configs

    ./build-buildroot \
      --config 'BR2_OPTIMIZE_3=y' \
      --config 'BR2_PACKAGE_SAMPLE_PACKAGE=y' \
      -- \
      sample_package-dirclean \
      sample_package-reconfigure \

    However, this approach might not be representative since calls to an unoptimized libc and other libraries will have a negative performance impact.

    Maybe you can get away with rebuilding libc, but I’m not sure that it will work properly.

    Kernel-wise it should be fine though due to: Disable kernel compiler optimizations

  • clean the build and rebuild from scratch:

    mv out out~
    ./build-buildroot --config 'BR2_OPTIMIZE_3=y'

19.3. Find Buildroot options with make menuconfig

make menuconfig is a convenient way to find Buildroot configurations:

cd "$(./getvar buildroot_build_dir)"
make menuconfig

Hit / and search for the settings.

Save and quit.

diff -u .config.olg .config

Then copy and paste the diff additions to buildroot_config/default to make them permanent.

19.4. Change user

At startup, we login automatically as the root user.

If you want to switch to another user to test some permissions, we have already created an user0 user through the user_table file, and you can just login as that user with:

login user0

and password:


Then test that the user changed with:


which gives:

uid=1000(user0) gid=1000(user0) groups=1000(user0)

19.4.1. Login as a non-root user without password

Replace on inittab:



::respawn:-/bin/login -f user0

-f forces login without asking for the password.

19.5. Add new Buildroot packages

First, see if you can’t get away without actually adding a new package, for example:

  • if you have a standalone C file with no dependencies besides the C standard library to be compiled with GCC, just add a new file under kernel_modules/user and you are done

  • if you have a dependency on a library, first check if Buildroot doesn’t have a package for it already with ls buildroot/package. If yes, just enable that package as explained at: Custom Buildroot configs

If none of those methods are flexible enough for you, you can just fork or hack up buildroot_packages/sample_package the sample package to do what you want.

For how to use that package, see: buildroot_packages directory.

Then iterate trying to do what you want and reading the manual until it works:

19.6. Remove Buildroot packages

Once you’ve built a package in to the image, there is no easy way to remove it.

See this for a sample manual workaround: PARSEC uninstall.


When adding new large package to the Buildroot root filesystem, it may fail with the message:

Maybe you need to increase the filesystem size (BR2_TARGET_ROOTFS_EXT2_SIZE)

The solution is to simply add:

./build-buildroot --config 'BR2_TARGET_ROOTFS_EXT2_SIZE="512M"'

where 512Mb is "large enough".

Note that dots cannot be used as in 1.5G, so just use Megs as in 1500M instead.

Unfortunately, TODO we don’t have a perfect way to find the right value for BR2_TARGET_ROOTFS_EXT2_SIZE. One good heuristic is:

du -hsx "$(./getvar --arch arm target_dir)"

Some promising ways to overcome this problem include:

19.7.1. SquashFS

SquashFS creation with mksquashfs does not take fixed sizes, and I have successfully booted from it, but it is readonly, which is unacceptable.

But then we could mount ramfs on top of it with OverlayFS to make it writable, but my attempts failed exactly as mentioned at OverlayFS.

19.8. Buildroot rebuild is slow when the root filesystem is large

Buildroot is not designed for large root filesystem images, and the rebuild becomes very slow when we add a large package to it.

This is due mainly to the pkg-generic GLOBAL_INSTRUMENTATION_HOOKS sanitation which go over the entire tree doing complex operations…​ I no like, in particular check_bin_arch and check_host_rpath

We have applied 983fe7910a73923a4331e7d576a1e93841d53812 to out Buildroot fork which removes part of the pain by not running:

>>>   Sanitizing RPATH in target tree

which contributed to a large part of the slowness.

Test how Buildroot deals with many files with:

./build-buildroot \
  --config 'BR2_PACKAGE_LKMC_MANY_FILES=y' \
  -- \
  lkmc_many_files-reconfigure \
  |& \
  ts -i '%.s' \
./build-buildroot |& ts -i '%.s'

and notice how the second build, which does not rebuilt the package at all, still gets stuck in the RPATH check forever without our Buildroot patch.

19.9. Report upstream bugs

When asking for help on upstream repositories outside of this repository, you will need to provide the commands that you are running in detail without referencing our scripts.

For example, QEMU developers will only want to see the final QEMU command that you are running.

For the configure and build, search for the Building and Configuring parts of the build log, then try to strip down all Buildroot related paths, to keep only options that seem to matter.

We make that easy by building commands as strings, and then echoing them before evaling.

So for example when you run:

./run --arch arm

the very first stdout output of that script is the actual QEMU command that is being run.

The command is also saved to a file for convenience:

cat "$(./getvar --arch arm run_cmd_file)"

which you can manually modify and execute during your experiments later:

vim "$(./getvar --arch arm run_cmd_file)"
./"$(./getvar --arch arm run_cmd_file)"

Next, you will also want to give the relevant images to save them time, see: release-zip.

Finally, do a clone of the relevant repository out of tree and reproduce the bug there, to be 100% sure that it is an actual upstream bug, and to provide developers with the cleanest possible commands.

For QEMU and Buildroot, we have the following convenient setups respectively:

20. Baremetal

Getting started at: Baremetal setup

20.1. Baremetal GDB step debug

GDB step debug works on baremetal exactly as it does on the Linux kernel, except that is is even cooler here since we can easily control and understand every single instruction that is being run!

For example, on the first shell:

./run --arch arm --baremetal interactive/prompt --wait-gdb

then on the second shell:

./run-gdb --arch arm --baremetal interactive/prompt -- main

Or if you are a tmux pro, do everything in one go with:

./run --arch arm --baremetal interactive/prompt --wait-gdb --tmux=main

Alternatively, to start from the very first executed instruction of our tiny Baremetal bootloaders:

./run --arch arm --baremetal interactive/prompt --wait-gdb --tmux=--no-continue

Now you can just stepi to when jumping into main to go to the C code in baremetal/interactive/prompt.c.

This is specially interesting for the executables that don’t use the bootloader from under baremetal/arch/<arch>/no_bootloader/*.S, e.g.:

./run --arch arm --baremetal arch/arm/no_bootloader/semihost_exit --wait-gdb --tmux=--no-continue

The cool thing about those examples is that you start at the very first instruction of your program, which gives more control.

aarch64 gem5 GDB step debug is broken as mentioned at: gem5 GDB step debug kernel aarch64.

20.2. Baremetal bootloaders

As can be seen from Baremetal GDB step debug, all examples under baremetal/, with the exception of baremetal/arch/<arch>/no_bootloader, start from our tiny bootloaders:

Out simplistic bootloaders basically setup up just enough system state to allow calling:

  • C functions such as exit from the assembly examples

  • the main of C examples itself

The most important things that we setup in the bootloaders are:

The C functions that become available as a result are:

It is not possible to call those C functions from the examples that don’t use a bootloader.

For this reason, we tend to create examples with bootloaders, as it is easier to write them portably.

20.3. Semihosting

Semihosting is a publicly documented interface specified by ARM Holdings that allows us to do some magic operations very useful in development.

Semihosting is implemented both on some real devices and on simulators such as QEMU and gem5 semihosting.

For example, the following code makes QEMU exit:

./run --arch arm --baremetal arch/arm/semihost_exit

That program program contains the code:

mov r0, #0x18
ldr r1, =#0x20026
svc 0x00123456

and we can see from the docs that 0x18 stands for the SYS_EXIT command.

This is also how we implement the exit(0) system call in C for QEMU for baremetal/exit.c through the Newlib via the function _exit at baremetal/lib/common.c.

Other magic operations we can do with semihosting besides exiting the on the host include:

  • read and write to host stdin and stdout

  • read and write to host files

Alternatives exist for some semihosting operations, e.g.:

  • UART IO for host stdin and stdout in both emulators and real hardware

  • m5ops for gem5, e.g. m5 exit makes the emulator quit

The big advantage of semihosting is that it is standardized across all ARM boards, and therefore allows you to make a single image that does those magic operations instead of having to compile multiple images with different magic addresses.

The downside of semihosting is that it is ARM specific. TODO is it an open standard that other vendors can implement?

In QEMU, we enable semihosting with:


Newlib 9c84bfd47922aad4881f80243320422b621c95dc already has a semi-hosting implementation at:


TODO: how to use it? Possible through crosstool-NG? In the worst case we could just copy it.


20.3.1. gem5 semihosting

For gem5, you need:

patch -d "$(./getvar gem5_src_dir)" -p 1 < patches/manual/gem5-semihost.patch

20.4. gem5 baremetal carriage return

TODO: our example is printing newlines without automatic carriage return \r as in:

enter a character
                 got: a

We use m5term by default, and if we try telnet instead:

telnet localhost 3456

it does add the carriage returns automatically.

20.5. Baremetal host packaged toolchain

For arm, some baremetal examples compile fine with:

sudo apt-get install gcc-arm-none-eabi qemu-system-arm
./build-baremetal --arch arm --prebuilt
./run --arch arm --baremetal interactive/prompt --prebuilt

However, there are as usual limitations to using prebuilts:

20.6. C++ baremetal

TODO I tried by there was an error. Not yet properly reported. Should not be hard in theory since libstdc++ is just part of GCC, as shown at:

20.7. GDB builtin CPU simulator

It is incredible, but GDB also has a CPU simulator inside of it as documented at:

TODO: any advantage over QEMU? I doubt it, mostly using it as as toy for now:

Without running ./run, do directly:

./run-gdb --arch arm --baremetal interactive/prompt --sim

Then inside GDB:


and now you can debug normally.

Enabled with the crosstool-NG configuration:


which by grepping crosstool-NG we can see does on GDB:

./configure --enable-sim

Those are not set by default on gdb-multiarch in Ubuntu 16.04.


20.7.1. GDB builtin CPU simulator userland

Since I had this compiled, I also decided to try it out on userland.

It just ignores the swi however, and does not forward syscalls to the host like QEMU does.

First it wouldn’t break, so I added -static to the Makefile, and then it started failing with:

Unhandled v6 thumb insn


help architecture

shows ARM version up to armv6, so maybe armv6 is not implemented?

20.8. ARM baremetal

In this section we will focus on learning ARM architecture concepts that can only learnt on baremetal setups.

Userland information can be found at:

20.8.1. ARM exception level

ARM exception levels are analogous to x86 rings.

Print the EL at the beginning of a baremetal simulation:

./run --arch arm --baremetal arch/arm/el
./run --arch aarch64 --baremetal arch/aarch64/el


The lower ELs are not mandated by the architecture, and can be controlled through command line options in QEMU and gem5.

./run --arch arm --baremetal arch/arm/el
./run --arch arm --baremetal arch/arm/el -- -machine virtualization=on
./run --arch arm --baremetal arch/arm/el -- -machine secure=on
./run --arch aarch64 --baremetal arch/aarch64/el
./run --arch aarch64 --baremetal arch/aarch64/el -- -machine virtualization=on
./run --arch aarch64 --baremetal arch/aarch64/el -- -machine secure=on

outputs respectively:


TODO: why is arm stuck at 19 which equals Supervisor mode?

In gem5, you can configure the lowest EL with:

./run --arch arm --baremetal arch/arm/el --gem5
cat "$(./getvar --arch arm --gem5 gem5_guest_terminal_file)"
./run --arch arm --baremetal arch/arm/el --gem5 -- --param 'system.have_virtualization = True'
cat "$(./getvar --arch arm --gem5 gem5_guest_terminal_file)"
./run --arch arm --baremetal arch/arm/el --gem5 -- --param 'system.have_security = True'
cat "$(./getvar --arch arm --gem5 gem5_guest_terminal_file)"
./run --arch aarch64 --baremetal arch/aarch64/el --gem5
cat "$(./getvar --arch aarch64 --gem5 gem5_guest_terminal_file)"
./run --arch aarch64 --baremetal arch/aarch64/el --gem5 -- --param 'system.have_virtualization = True'
cat "$(./getvar --arch aarch64 --gem5 gem5_guest_terminal_file)"
./run --arch aarch64 --baremetal arch/aarch64/el --gem5 -- --param 'system.have_security = True'
cat "$(./getvar --arch aarch64 --gem5 gem5_guest_terminal_file)"



20.8.2. ARM multicore

./run --arch aarch64 --baremetal arch/aarch64/multicore --cpus 2
./run --arch aarch64 --baremetal arch/aarch64/multicore --cpus 2 --gem5
./run --arch arm --baremetal arch/aarch64/multicore --cpus 2
./run --arch arm --baremetal arch/aarch64/multicore --cpus 2 --gem5


CPU 0 of this program enters a spinlock loop: it repeatedly checks if a given memory address is 1.

So, we need CPU 1 to come to the rescue and set that memory address to 1, otherwise CPU 0 will be stuck there forever!

Don’t believe me? Then try:

./run --arch aarch64 --baremetal arch/aarch64/multicore --cpus 1

and watch it hang forever.

Note that if you try the same thing on gem5:

./run --arch aarch64 --baremetal arch/aarch64/multicore --cpus 1 --gem5

then the gem5 actually exits, but with a different message:

Exiting @ tick 18446744073709551615 because simulate() limit reached

as opposed to the expected:

Exiting @ tick 36500 because m5_exit instruction encountered

since gem5 is able to detect when nothing will ever happen, and exits.

When GDB step debugging, switch between cores with the usual thread commands, see also: GDB step debug multicore userland. WFE and SEV

The WFE and SEV instructions are just hints: a compliant implementation can treat them as NOPs.

However, likely no implementation likely does (TODO confirm), since:

  • WFE puts the core in a low power mode

  • SEV wakes up cores from a low power mode

and power consumption is key in ARM applications.

In QEMU 3.0.0, SEV is a NOPs, and WFE might be, but I’m not sure, see:

    case 2: /* WFE */
        if (!(tb_cflags(s->base.tb) & CF_PARALLEL)) {
            s->base.is_jmp = DISAS_WFE;
    case 4: /* SEV */
    case 5: /* SEVL */
        /* we treat all as NOP at least for now */

TODO: what does the WFE code do? How can it not be a NOP if SEV is a NOP? might explain why, but it is Chinese to me (I only understand 30% ;-)):

 * For WFI we will halt the vCPU until an IRQ. For WFE and YIELD we
 * only call the helper when running single threaded TCG code to ensure
 * the next round-robin scheduled vCPU gets a crack. In MTTCG mode we
 * just skip this instruction. Currently the SEV/SEVL instructions
 * which are *one* of many ways to wake the CPU from WFE are not
 * implemented so we can't sleep like WFI does.

For gem5 however, if we comment out the SVE instruction, then it actually exits with simulate() limit reached, so the CPU truly never wakes up, which is a more realistic behaviour.

The following Raspberry Pi bibliography helped us get this sample up and running: PSCI

In QEMU, CPU 1 starts in a halted state. This can be observed from GDB, where:

info threads

shows something like:

* 1    Thread 1 (CPU#0 [running]) mystart
  2    Thread 2 (CPU#1 [halted ]) mystart

To wake up CPU 1 on QEMU, we must use the Power State Coordination Interface (PSCI) which is documented at:

This interface uses HVC calls, and the calling convention is documented at "SMC CALLING CONVENTION"

If we boot the Linux kernel on QEMU and dump the auto-generated device tree, we observe that it contains the address of the PSCI CPU_ON call:

        psci {
                method = "hvc";
                compatible = "arm,psci-0.2", "arm,psci";
                cpu_on = <0xc4000003>;
                migrate = <0xc4000005>;
                cpu_suspend = <0xc4000001>;
                cpu_off = <0x84000002>;

The Linux kernel wakes up the secondary cores in this exact same way at: We first actually got it working here by grepping the kernel and step debugging that call :-)

In gem5, CPU 1 starts woken up from the start, so PSCI is not needed. TODO gem5 actually blows up if we try to do the hvc call, understand why. DMB

TODO: create and study a minimal examples in gem5 where the DMB instruction leads to less cycles:

20.9. How we got some baremetal stuff to work

It is nice when thing just work.

But you can also learn a thing or two from how I actually made them work in the first place.

20.9.1. Find the UART address

Enter the QEMU console:

Ctrl-X C

Then do:

info mtree

And look for pl011:

    0000000009000000-0000000009000fff (prio 0, i/o): pl011

On gem5, it is easy to find it on the source. We are using the machine RealView_PBX, and a quick grep leads us to:

class RealViewPBX(RealView):
    uart = Pl011(pio_addr=0x10009000, int_num=44)

20.9.2. aarch64 baremetal NEON setup

Inside baremetal/lib/aarch64.S there is a chunk of code called "NEON setup".

Without that, the printf:

printf("got: %c\n", c);

compiled to a:

str    q0, [sp, #80]

which uses NEON registers, and goes into an exception loop.

It was a bit confusing because there was a previous printf:

printf("enter a character\n");

which did not blow up because GCC compiles it into puts directly since it has no arguments, and that does not generate NEON instructions.

The last instructions ran was found with:


or by hacking the QEMU CLI to contain:

-D log.log -d in_asm

I could not find any previous NEON instruction executed so this led me to suspect that some NEON initialization was required:

We then tried to copy the code from the "Bare-metal Boot Code for ARMv8-A Processors" document:

// Disable trapping of accessing in EL3 and EL2.
// Disable access trapping in EL1 and EL0.
MOV X1, #(0x3 << 20) // FPEN disables trapping to EL1.

but it entered an exception loop at MSR CPTR_EL3, XZR.

We then found out that QEMU starts in EL1, and so we kept just the EL1 part, and it worked. Related:

20.10. Baremetal bibliography contains an alternative working baremetal setup. Our setup has more features at the time of writing however. Usage:

# Build gem5.
git clone
cd gem5
git checkout 60600f09c25255b3c8f72da7fb49100e2682093a
scons --ignore-style -j`nproc` build/ARM/gem5.opt
cd ..

# Build example.
sudo apt-get install gcc-arm-none-eabi
git clone
cd gem5.bare-metal
git checkout 6ad1069d4299b775b5491e9252739166bfac9bfe
cd Simple
make CROSS_COMPILE_DIR=/usr/bin

# Run example.
../../gem5/default/build/ARM/gem5.opt' \
  ../../gem5/configs/example/' \
  --bare-metal \
  --disk-image="$(pwd)/../common/fake.iso" \
  --kernel="$(pwd)/main.elf" \
  --machine-type=RealView_PBX \
  --mem-size=256MB \

21. Benchmark this repo

In this section document how benchmark builds and runs of this repo, and how to investigate what the bottleneck is.

Ideally, we should setup an automated build server that benchmarks those things continuously for us, but our Travis attempt failed.

So currently, we are running benchmarks manually when it seems reasonable and uploading them to:

All benchmarks were run on the P51 machine, unless stated otherwise.

Run all benchmarks and upload the results:

cd ..
git clone
cd -
./bench-all -A

21.1. Travis

We tried to automate it on Travis with .travis.yml but it hits the current 50 minute job timeout: And I bet it would likely hit a disk maxout either way if it went on.

21.2. Benchmark this repo benchmarks

21.2.1. Benchmark Linux kernel boot

Run all kernel boot benchmarks for one arch:

./build-bench-boot --size 3 && ./bench-boot --size 3
cat "$(./getvar bench_boot)"

Sample results at 8fb9db39316d43a6dbd571e04dd46ae73915027f:

cmd ./run --arch x86_64 --eval '/poweroff.out'
time 8.25
exit_status 0

cmd ./run --arch x86_64 --eval '/poweroff.out' --kvm
time 1.22
exit_status 0

cmd ./run --arch x86_64 --eval '/poweroff.out' --trace exec_tb
time 8.83
exit_status 0
instructions 2244297

cmd ./run --arch x86_64 --eval 'm5 exit' --gem5
time 213.39
exit_status 0
instructions 318486337

cmd ./run --arch arm --eval '/poweroff.out'
time 6.62
exit_status 0
cmd ./run --arch arm --eval '/poweroff.out' --trace exec_tb
time 6.90
exit_status 0
instructions 776374

cmd ./run --arch arm --eval 'm5 exit' --gem5
time 118.46
exit_status 0
instructions 153023392

cmd ./run --arch arm --eval 'm5 exit' --gem5 -- --cpu-type=HPI --caches --l2cache --l1d_size=1024kB --l1i_size=1024kB --l2_size=1024kB --l3_size=1024kB
time 2250.40
exit_status 0
instructions 151981914

cmd ./run --arch aarch64 --eval '/poweroff.out'
time 4.94
exit_status 0

cmd ./run --arch aarch64 --eval '/poweroff.out' --trace exec_tb
time 5.04
exit_status 0
instructions 233162

cmd ./run --arch aarch64 --eval 'm5 exit' --gem5
time 70.89
exit_status 0
instructions 124346081

cmd ./run --arch aarch64 --eval 'm5 exit' --gem5 -- --cpu-type=HPI --caches --l2cache --l1d_size=1024kB --l1i_size=1024kB --l2_size=1024kB --l3_size=1024kB
time 381.86
exit_status 0
instructions 124564620

cmd ./run --arch aarch64 --eval 'm5 exit' --gem5 --gem5-build-type fast
time 58.00
exit_status 0
instructions 124346081

cmd ./run --arch aarch64 --eval 'm5 exit' --gem5 --gem5-build-type debug
time 1022.03
exit_status 0
instructions 124346081

TODO: aarch64 gem5 and QEMU use the same kernel, so why is the gem5 instruction count so much much higher? gem5 arm HPI boot takes much longer than aarch64

TODO 62f6870e4e0b384c4bd2d514116247e81b241251 takes 33 minutes to finish at 62f6870e4e0b384c4bd2d514116247e81b241251:

cmd ./run --arch arm --eval 'm5 exit' --gem5 -- --caches --cpu-type=HPI

while aarch64 only 7 minutes.

I had previously documented on README 10 minutes at: 2eff007f7c3458be240c673c32bb33892a45d3a0 found with git log search for 10 minutes. But then I checked out there, run it, and kernel panics before any messages come out. Lol?

The cycle count is higher for arm, 350M vs 250M for aarch64, not nowhere near the 5x runtime time increase.

A quick look at the boot logs show that they are basically identical in structure: the same operations appear more ore less on both, and there isn’t one specific huge time pit in arm: it is just that every individual operation seems to be taking a lot longer.

21.2.2. Benchmark builds

The build times are calculated after doing ./configure and make source, which downloads the sources, and basica