Bare metal: hello from the UART on QEMU

On QEMU’s RISC-V virt board started with -bios none, the first instruction of your program runs at 0x80000000, and nothing of yours has run before it: no loader you wrote, no stack, no C library and no system calls. Such a program is bare metalbare metal: Software that runs directly on the hardware with no operating system under it. It places itself in memory through its linker script, sets up its own stack and drives devices through their registers., the only software on the machine, so it sets up its own stack and prints by storing bytes to a device.

You will build one for RISC-V and one for AArch64. Each sends a hello message through its board’s UARTUART: Universal asynchronous receiver-transmitter, the device that turns bytes into the bits of a serial line and back. A program sends a byte by writing it to the UART's data register. and then asks QEMU to end the run with a status.

A bare-metal program sets up what an operating system would

Under Linux or macOS the kernel’s loaderloader: The kernel code that reads an executable's load commands or program headers, maps each segment into the new process with the right permissions and jumps to the entry-point address. More in “From source to executable: objects and linking” maps each segment and builds a stack before the C library’s startup codestart-up code: The code a compiler driver links around a C program, such as crt1.o's _start, which reads the initial stack, prepares the C library, calls main and passes its return value to exit. More in “Process startup: argc, argv, envp and auxv” calls main, as process startup shows. On bare metal nobody does any of that. A linker scriptlinker script: A file that tells the linker where each output section goes in memory and which symbols to define. A bare-metal image needs one because no operating system's loader chooses its addresses. fixes the image’s load addressload address: The memory address a program's bytes are copied to before it runs. A bare-metal image is linked for the address its board's reset code or loader uses., the first instruction sets the stack pointerstack pointer: The register that addresses the top of the stack: rsp on x86-64, sp on AArch64 and sp (x2) on RISC-V. Push, pop and function prologues move it; losing it loses the stack. More in “Registers on x86-64, AArch64 and RISC-V”, and there is no system call to ask for anything.

Output goes through memory-mapped I/Omemory-mapped I/O: Reaching a device through ordinary loads and stores: the device answers a range of physical addresses, so a store there writes one of its registers instead of RAM.: a device answers a range of physical addresses, so an ordinary store to one of them is a command to the device. On the RISC-V board a byte stored to 0x10000000 goes to the UART’s transmit register. With -bios none the hart runs the program in machine mode, the highest privilege modeprivilege mode: RISC-V's name for a privilege level: U-mode for applications, S-mode for an operating-system kernel and M-mode, machine mode, the highest and the only one every RISC-V processor must have. More in “Privilege levels, exceptions and interrupts” of privilege levels and exceptions, so every address is open to it. The AArch64 board starts its core at EL1, since it leaves EL2 and EL3 off unless asked.

QEMU’s virt boards publish where RAM and each device live

virt is a board QEMU designed for guests rather than a copy of a real chip. Each one is a table of base addresses in QEMU’s source, hw/riscv/virt.c and hw/arm/virt.c.

For an ELF image on the AArch64 board, QEMU writes the device treedevice tree: A data structure that describes a board's hardware: where its RAM is and which devices it has, at which addresses and with which interrupts. Firmware or an emulator passes it to the software it starts. as a 1 MiB block at the first byte of RAM, and leaves it out when the image starts inside that megabyte, so the program is linked 2 MiB in, at 0x40200000. QEMU’s Arm page promises only the RAM and flash addresses, so a portable program reads every other address from the device tree.

The image is linked at the board’s RAM, and the ELF file proves it

hello.s sets sp, stores the message to the UART one byte at a time and then stores 0x5555 to the test device. The AArch64 twin does the same through the PL011 and leaves with a semihostingsemihosting: A convention by which a program asks the debugger or emulator running it for a host service, such as printing text or ending the run, through a special instruction. Arm defines it, and QEMU answers it when started with -semihosting. call, which asks QEMU itself to end the run. link.ld places the .text.boot section, the one that holds _start, first, at 0x80000000.

# hello.s: a bare-metal program for QEMU's RISC-V virt machine, started with -bios none.
# Only QEMU's reset code runs before _start, so the program sets up its own stack.
    .equ UART0, 0x10000000          # NS16550A UART: offset 0 is the transmit register
    .equ TEST, 0x100000             # SiFive test device: a write of 0x5555 ends QEMU

    .section .text.boot, "ax"
    .globl _start
_start:
    la sp, stack_top                # the stack grows down from the end of .bss
    la a0, msg
    li t1, UART0
next:
    lbu t0, 0(a0)                   # one byte of the message
    beqz t0, done                   # a zero byte ends it
    sb t0, 0(t1)                    # store it to the UART's transmit register
    addi a0, a0, 1
    j next
done:
    li t1, TEST
    li t0, 0x5555                   # "pass"
    sw t0, 0(t1)
park:
    wfi                             # if nothing ends the machine, wait here
    j park

    .section .rodata
msg: .asciz "Hello from bare-metal RISC-V\n"

    .section .bss
    .balign 16
    .space 4096                     # 4 KiB of stack
stack_top:

// hello.s: a bare-metal program for QEMU's AArch64 virt machine, started with -semihosting.
    .equ UART0, 0x09000000          // PL011 UART: offset 0 is the data register

    .section .text.boot, "ax"
    .globl _start
_start:
    ldr x0, =stack_top
    mov sp, x0                      // the stack grows down from the end of .bss
    ldr x1, =UART0
    adr x2, msg
next:
    ldrb w3, [x2], #1               // one byte, then step to the next
    cbz w3, done                    // a zero byte ends the message
    strb w3, [x1]                   // store it to the UART's data register
    b next
done:
    mov x0, #0x18                   // semihosting operation SYS_EXIT
    adr x1, exit_block              // the address of its two-word argument block
    hlt #0xf000                     // the A64 semihosting call
park:
    wfi
    b park

    .section .rodata
    .balign 8
exit_block: .quad 0x20026, 0        // reason ADP_Stopped_ApplicationExit, exit code 0
msg: .asciz "Hello from bare-metal AArch64\n"

    .section .bss
    .balign 16
    .space 4096                     // 4 KiB of stack
stack_top:

/* link.ld: place hello.s where QEMU's RISC-V virt machine starts it with -bios none. */
/* QEMU's reset code jumps to the first byte of RAM, 0x80000000, whatever the ELF entry says. */
ENTRY(_start)
SECTIONS
{
  . = 0x80000000;                        /* the first byte of RAM on virt */
  .text   : { *(.text.boot) *(.text*) }  /* _start first, so it lands at 0x80000000 */
  .rodata : { *(.rodata*) }
  .data   : { *(.data*) }
  .bss    : { *(.bss*) }
}

"""Build both hello programs as bare-metal ELF images and read back where they will load."""

import pathlib
import sys

sys.path.insert(0, str(pathlib.Path(__file__).parent / "sessions"))
import session

session.run("""
# Assemble for 64-bit RISC-V and link with the script that starts at 0x80000000
clang-23 --target=riscv64-unknown-elf -march=rv64gc -mabi=lp64 -c riscv/hello.s -o hello_rv.o
ld.lld -T riscv/link.ld hello_rv.o -o hello_rv.elf
# The header names the machine and the entry point
llvm-readelf -h hello_rv.elf | grep -E "Machine|Entry"
# The program headers: what a loader copies, to which address, with which permissions
llvm-readelf -lW hello_rv.elf | grep -E "Type|LOAD"
# The code at the first byte of RAM: stack, message address, then the store to the UART
llvm-objdump -d --no-show-raw-insn hello_rv.elf | grep -E "^8000"
# The AArch64 twin, linked 2 MiB into RAM
clang-23 --target=aarch64-none-elf -c aarch64/hello.s -o hello_a64.o
ld.lld -T aarch64/link.ld hello_a64.o -o hello_a64.elf
llvm-readelf -h hello_a64.elf | grep -E "Machine|Entry"
llvm-objdump -d --no-show-raw-insn hello_a64.elf | grep -E "^4020" | head -n 7
""")

# Assemble for 64-bit RISC-V and link with the script that starts at 0x80000000
$ clang-23 --target=riscv64-unknown-elf -march=rv64gc -mabi=lp64 -c riscv/hello.s -o hello_rv.o
$ ld.lld -T riscv/link.ld hello_rv.o -o hello_rv.elf
# The header names the machine and the entry point
$ llvm-readelf -h hello_rv.elf | grep -E "Machine|Entry"
  Machine:                           RISC-V
  Entry point address:               0x80000000
# The program headers: what a loader copies, to which address, with which permissions
$ llvm-readelf -lW hello_rv.elf | grep -E "Type|LOAD"
  Type           Offset   VirtAddr           PhysAddr           FileSiz  MemSiz   Flg Align
  LOAD           0x001000 0x0000000080000000 0x0000000080000000 0x000038 0x000038 R E 0x1000
  LOAD           0x001038 0x0000000080000038 0x0000000080000038 0x00001e 0x00001e R   0x1000
  LOAD           0x001060 0x0000000080000060 0x0000000080000060 0x000000 0x001000 RW  0x1000
# The code at the first byte of RAM: stack, message address, then the store to the UART
$ llvm-objdump -d --no-show-raw-insn hello_rv.elf | grep -E "^8000"
80000000:      	auipc	sp, 0x1
80000004:      	addi	sp, sp, 0x60
80000008:      	auipc	a0, 0x0
8000000c:      	addi	a0, a0, 0x30
80000010:      	lui	t1, 0x10000
80000014:      	lbu	t0, 0x0(a0)
80000018:      	beqz	t0, 0x80000024 <done>
8000001c:      	sb	t0, 0x0(t1)
80000020:      	addi	a0, a0, 0x1
80000022:      	j	0x80000014 <next>
80000024:      	lui	t1, 0x100
80000028:      	lui	t0, 0x5
8000002a:      	addi	t0, t0, 0x555
8000002e:      	sw	t0, 0x0(t1)
80000032:      	wfi
80000036:      	j	0x80000032 <park>
# The AArch64 twin, linked 2 MiB into RAM
$ clang-23 --target=aarch64-none-elf -c aarch64/hello.s -o hello_a64.o
$ ld.lld -T aarch64/link.ld hello_a64.o -o hello_a64.elf
$ llvm-readelf -h hello_a64.elf | grep -E "Machine|Entry"
  Machine:                           AArch64
  Entry point address:               0x40200000
$ llvm-objdump -d --no-show-raw-insn hello_a64.elf | grep -E "^4020" | head -n 7
40200000:      	ldr	x0, 0x40200038 <park+0xc>
40200004:      	mov	sp, x0
40200008:      	mov	x1, #0x9000000          // =150994944
4020000c:      	adr	x2, 0x40200050 <msg>
40200010:      	ldrb	w3, [x2], #0x1
40200014:      	cbz	w3, 0x40200020 <done>
40200018:      	strb	w3, [x1]

The entry pointentry point: The address where the kernel's loader starts a program: the value the executable's header names (e_entry in an ELF header, LC_MAIN in a Mach-O file). The Linux convention is the symbol _start; a C program's main runs later, called by the startup code. More in “First program: return an exit status” is 0x80000000, and the three LOAD program headersprogram header: An entry of an ELF file's program header table that describes one segment: its type, where its bytes are in the file, the address to load them at, its size in memory and its permissions. are the code (R E, 0x38 bytes), the message (R, 0x1e bytes: 29 characters and a zero byte) and a read-write segment of 0x1000 bytes with nothing in the file, which is the stack. auipc and addi build sp = 0x80001060 from the pc, and lui t1, 0x10000 loads the UART’s address, 0x10000000. The AArch64 image enters at 0x40200000. The script below starts both images on QEMU in your Linux lab:

#!/bin/sh
# Run the lesson's images on QEMU's virt machines, in your Linux lab (QEMU's system emulators installed).
# -machine virt       the board: RAM, UART and exit device at the addresses the lesson uses
# -bios none          RISC-V only: no firmware, so the reset code jumps straight to 0x80000000
# -cpu cortex-a57     AArch64 only: the virt default is a 32-bit core, so name a 64-bit one
# -nographic          no window: the UART is wired to this terminal (Ctrl-a x leaves QEMU by hand)
# -semihosting        AArch64 only: let hlt #0xf000 reach QEMU, so SYS_EXIT can end it
# -kernel <file>      load the ELF image's segments at the addresses in its program headers
set -eu
clang --target=riscv64-unknown-elf -march=rv64gc -mabi=lp64 -c riscv/hello.s -o hello_rv.o
ld.lld -T riscv/link.ld hello_rv.o -o hello_rv.elf
clang --target=aarch64-none-elf -c aarch64/hello.s -o hello_a64.o
ld.lld -T aarch64/link.ld hello_a64.o -o hello_a64.elf

status=0
qemu-system-riscv64 -machine virt -bios none -nographic -kernel hello_rv.elf || status=$?
echo "qemu exit status: $status"

status=0
qemu-system-aarch64 -machine virt -cpu cortex-a57 -nographic -semihosting -kernel hello_a64.elf || status=$?
echo "qemu exit status: $status"

# Write the device tree QEMU generates for each board to a file and stop, to read its memory map
qemu-system-riscv64 -machine virt,dumpdtb=virt-riscv.dtb -bios none -nographic
qemu-system-aarch64 -machine virt,dumpdtb=virt-arm.dtb -cpu cortex-a57 -nographic

import pathlib
import sys

sys.path.insert(0, str(pathlib.Path(__file__).parent / "sessions"))
import linux_lab

# In the Linux lab: both images built and run on QEMU's virt boards, then each board's device tree written to a file.
linux_lab.run("""
sh run_on_qemu.sh
ls virt-*.dtb
""")

$ sh run_on_qemu.sh
Hello from bare-metal RISC-V
qemu exit status: 0
Hello from bare-metal AArch64
qemu exit status: 0
$ ls virt-*.dtb
virt-arm.dtb  virt-riscv.dtb

Both messages arrived, QEMU ended with status 0 each time, and the last two lines wrote both device trees to files.

A linker script can also name regions and segments and stop a bad link, and a real UART needs a driver that waits before each byte.

Practise: change the image and predict the read-back

Copy hello.s, link.ld and the build session, and predict each result before you run the copy.

1. Lengthen the message by five characters and predict the file size of the second LOAD segment.
2. Change . = 0x80000000; to . = 0x80200000; in link.ld, then predict the entry point and the value the first two instructions put in sp.
3. Link the AArch64 object with the RISC-V link.ld and predict its entry point. A board gets 128 MiB of RAM unless -m asks for more: use the table to say why the AArch64 board has none at that address.

Placing code, data and a stack with a linker script Pro: opens with a Pro, Premium or Ultimate pass

Driving a UART properly and leaving QEMU with a status Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

What is memory-mapped I/O, and how does a bare-metal program on QEMU’s RISC-V virt board print one character with it?

A device answers a range of physical addresses, so loads and stores there reach its registers instead of RAM: that is memory-mapped I/O. To print a character, the program stores its byte to the UART’s transmit register, the first byte of the NS16550A at 0x10000000 on QEMU’s RISC-V virt board. No system call is involved: the store itself is the command. The address comes from the board’s memory map, in QEMU’s source or the device tree it passes in.

Three longer questions in the module’s bank build on this one: an image that prints nothing, failures a test job reads as passes, and the move to a real board.

Key takeaways

• A bare-metal program is the only software on the machine: its linker script fixes where it loads, and its first instructions set up its stack.
• Devices are reached by memory-mapped I/O: on QEMU’s RISC-V virt board a byte stored to 0x10000000 goes to the UART, and 0x5555 stored to 0x100000 ends the run.
• With -bios none, QEMU’s RISC-V reset code jumps to 0x80000000, the first byte of RAM, whatever the ELF entry point says, so the image must begin there.
• llvm-readelf -h -lW shows an image’s entry point and the segments a loader copies, before the image runs.