# Linux Kernel Module Cheat

#### 2.9.2. Baremetal setup getting started

Every `.c` file inside baremetal/ and `.S` file inside `baremetal/arch/<arch>/` generates a separate baremetal image.

For example, to run baremetal/arch/aarch64/dump_regs.c in QEMU do:

    ./setup
    ./build --arch aarch64 --download-dependencies qemu-baremetal
    ./run --arch aarch64 --baremetal baremetal/arch/aarch64/dump_regs.c

And the terminal prints the values of certain system registers. This example prints registers that are only accessible from EL1 or higher, and thus could not be run in userland.

In addition to the examples under baremetal/, several of the userland examples can also be run in baremetal! This is largely due to the awesomeness of Newlib.

The examples that work include most C examples that don’t rely on complicated syscalls such as threads, and almost all the Userland assembly examples.

The exact list of userland programs that work in baremetal is specified in path_properties.py with the `baremetal` property, but you can also easily find it out with a baremetal test dry run:

    ./test-executables --arch aarch64 --dry-run --mode baremetal

For example, we can run the C hello world userland/c/hello.c simply as:

    ./run --arch aarch64 --baremetal userland/c/hello.c

and that outputs to the serial port the string:

    hello

which QEMU shows on the host terminal.

To modify a baremetal program, simply edit the file, e.g.

    vim userland/c/hello.c

and rebuild:

    ./build-baremetal --arch aarch64
    ./run --arch aarch64 --baremetal userland/c/hello.c

`./build qemu-baremetal` that we run previously is only needed for the initial build. That script calls build-baremetal for us, in addition to building prerequisites such as QEMU and crosstool-NG.

`./build-baremetal` uses crosstool-NG, and so it must be preceded by build-crosstool-ng, which `./build qemu-baremetal` also calls.

Now let’s run userland/arch/aarch64/add.S:

    ./run --arch aarch64 --baremetal userland/arch/aarch64/add.S

This time, the terminal does not print anything, which indicates success: if you look into the source, you will see that we just have an assertion there.

You can see a sample assertion fail in userland/c/assert_fail.c:

    ./run --arch aarch64 --baremetal userland/c/assert_fail.c

and the terminal contains:

    lkmc_exit_status_134
    error: simulation error detected by parsing logs

and the exit status of our script is 1:

    echo $?

You can run all the baremetal examples in one go and check that all assertions passed with:

    ./test-executables --arch aarch64 --mode baremetal

To use gem5 instead of QEMU do:

    ./setup
    ./build --download-dependencies gem5-baremetal
    ./run --arch aarch64 --baremetal userland/c/hello.c --emulator gem5

and then as usual open a shell with:

    ./gem5-shell

Or as usual, tmux users can do both in one go with:

    ./run --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 --tmux

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

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

    echo "$(./getvar --arch aarch64 --baremetal userland/c/hello.c --emulator qemu image)"
    echo "$(./getvar --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 image)"

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

    echo "$(./getvar --arch aarch64 --emulator qemu image)"
    echo "$(./getvar --arch aarch64 --emulator 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 --emulator gem5 --machine RealViewPBX
    ./run --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 --machine RealViewPBX

see also: Section 24.18, “gem5 ARM platforms”.

This generates yet new separate images with new magic constants:

    echo "$(./getvar --arch aarch64 --baremetal userland/c/hello.c --emulator gem5 --machine VExpress_GEM5_V1 image)"
    echo "$(./getvar --arch aarch64 --baremetal userland/c/hello.c --emulator 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 baremetal programming, it is likely that you will want to learn userland assembly first, see: Section 28, “Userland assembly”.

For more information on baremetal, see the section: Section 33, “Baremetal”.

The following subjects are particularly important:

- Tracing

- Baremetal GDB step debug