QEMU

    IMPORTANT We’ll use the name “app” for the project name in this tutorial. Whenever you see the word “app” you should replace it with the name you selected for your project. Or, you could also name your project “app” and avoid the substitutions.

    We’ll use the cortex-m-quickstart project template to generate a new project from it. The created project will contain a barebone application: a good starting point for a new embedded rust application. In addition, the project will contain an directory, with several separate applications, highlighting some of the key embedded rust functionality.

    First install cargo-generate

    Then generate a new project

    1. cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart
    1.  Project Name: app
    2.  Creating project called `app`...
    3.  Done! New project created /tmp/app
    1. cd app

    Clone the repository

    1. git clone https://github.com/rust-embedded/cortex-m-quickstart app
    2. cd app

    And then fill in the placeholders in the Cargo.toml file

    1. [package]
    2. authors = ["{{authors}}"] # "{{authors}}" -> "John Smith"
    3. edition = "2018"
    4. name = "{{project-name}}" # "{{project-name}}" -> "app"
    5. version = "0.1.0"
    7. # ..
    9. [[bin]]
    10. name = "{{project-name}}" # "{{project-name}}" -> "app"
    11. test = false
    12. bench = false

    Grab the latest snapshot of the cortex-m-quickstart template and extract it.

    1. curl -LO https://github.com/rust-embedded/cortex-m-quickstart/archive/master.zip
    2. unzip master.zip
    3. mv cortex-m-quickstart-master app
    4. cd app

    Or you can browse to cortex-m-quickstart, click the green “Clone or download” button and then click “Download ZIP”.

    Then fill in the placeholders in the Cargo.toml file as done in the second part of the “Using git“ version.

    Program Overview

    For convenience here are the most important parts of the source code in src/main.rs:

    1. #![no_std]
    2. #![no_main]
    4. use panic_halt as _;
    6. use cortex_m_rt::entry;
    8. #[entry]
    9. fn main() -> ! {
    10.     loop {
    11.         // your code goes here
    12.     }
    13. }

    This program is a bit different from a standard Rust program so let’s take a closer look.

    #![no_std] indicates that this program will not link to the standard crate, std. Instead it will link to its subset: the core crate.

    #![no_main] indicates that this program won’t use the standard main interface that most Rust programs use. The main (no pun intended) reason to go with no_main is that using the main interface in no_std context requires nightly.

    use panic_halt as _;. This crate provides a panic_handler that defines the panicking behavior of the program. We will cover this in more detail in the chapter of the book.

    #[entry] is an attribute provided by the crate that’s used to mark the entry point of the program. As we are not using the standard main interface we need another way to indicate the entry point of the program and that’d be #[entry].

    fn main() -> !. Our program will be the only process running on the target hardware so we don’t want it to end! We use a divergent function (the -> ! bit in the function signature) to ensure at compile time that’ll be the case.

    The next step is to cross compile the program for the Cortex-M3 architecture. That’s as simple as running cargo build --target $TRIPLE if you know what the compilation target ($TRIPLE) should be. Luckily, the .cargo/config.toml in the template has the answer:

    1. tail -n6 .cargo/config.toml
    1. [build]
    2. # Pick ONE of these compilation targets
    3. # target = "thumbv6m-none-eabi"    # Cortex-M0 and Cortex-M0+
    4. target = "thumbv7m-none-eabi"    # Cortex-M3
    5. # target = "thumbv7em-none-eabi"   # Cortex-M4 and Cortex-M7 (no FPU)
    6. # target = "thumbv7em-none-eabihf" # Cortex-M4F and Cortex-M7F (with FPU)

    To cross compile for the Cortex-M3 architecture we have to use thumbv7m-none-eabi. That target is not automatically installed when installing the Rust toolchain, it would now be a good time to add that target to the toolchain, if you haven’t done it yet:

    1. rustup target add thumbv7m-none-eabi

    Since the thumbv7m-none-eabi compilation target has been set as the default in your .cargo/config.toml file, the two commands below do the same:

    1. cargo build --target thumbv7m-none-eabi
    2. cargo build

    Now we have a non-native ELF binary in target/thumbv7m-none-eabi/debug/app. We can inspect it using cargo-binutils.

    With cargo-readobj we can print the ELF headers to confirm that this is an ARM binary.

    1. cargo readobj --bin app -- --file-headers

    Note that:

    • --bin app is sugar for inspect the binary at target/$TRIPLE/debug/app
    • --bin app will also (re)compile the binary, if necessary
    1. ELF Header:
    2.   Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
    3.   Class:                             ELF32
    4.   Data:                              2's complement, little endian
    5.   Version:                           1 (current)
    6.   OS/ABI:                            UNIX - System V
    7.   ABI Version:                       0x0
    8.   Type:                              EXEC (Executable file)
    10.   Version:                           0x1
    11.   Entry point address:               0x405
    12.   Start of program headers:          52 (bytes into file)
    13.   Start of section headers:          153204 (bytes into file)
    14.   Size of this header:               52 (bytes)
    15.   Size of program headers:           32 (bytes)
    16.   Number of program headers:         2
    17.   Size of section headers:           40 (bytes)
    18.   Number of section headers:         19
    19.   Section header string table index: 18

    we use --release to inspect the optimized version

    1. app  :
    2. section             size        addr
    3. .vector_table       1024         0x0
    4. .text                 92       0x400
    5. .rodata                0       0x45c
    6. .data                  0  0x20000000
    7. .bss                   0  0x20000000
    8. .debug_str          2958         0x0
    9. .debug_loc            19         0x0
    10. .debug_abbrev        567         0x0
    11. .debug_info         4929         0x0
    12. .debug_ranges         40         0x0
    13. .debug_macinfo         1         0x0
    14. .debug_pubnames     2035         0x0
    15. .debug_pubtypes     1892         0x0
    16. .ARM.attributes       46         0x0
    17. .debug_frame         100         0x0
    18. .debug_line          867         0x0
    19. Total              14570

    IMPORTANT: ELF files contain metadata like debug information so their size on disk does not accurately reflect the space the program will occupy when flashed on a device. Always use cargo-size to check how big a binary really is.

    cargo-objdump can be used to disassemble the binary.

    1. cargo objdump --bin app --release -- --disassemble --no-show-raw-insn --print-imm-hex
    1. app:  file format ELF32-arm-little
    3. Disassembly of section .text:
    4. main:
    5.      400: bl  #0x256
    6.      404: b #-0x4 <main+0x4>
    8. Reset:
    9.      406: bl  #0x24e
    10.      40a: movw  r0, #0x0
    11.      < .. truncated any more instructions .. >
    13. DefaultHandler_:
    14.      656: b #-0x4 <DefaultHandler_>
    16. UsageFault:
    17.      657: strb  r7, [r4, #0x3]
    19. DefaultPreInit:
    20.      658: bx  lr
    22. __pre_init:
    23.      659: strb  r7, [r0, #0x1]
    25. __nop:
    26.      65a: bx  lr
    28. HardFaultTrampoline:
    29.      65c: mrs r0, msp
    30.      660: b #-0x2 <HardFault_>
    32. HardFault_:
    33.      662: b #-0x4 <HardFault_>
    35. HardFault:
    36.      663: <unknown>

    Next, let’s see how to run an embedded program on QEMU! This time we’ll use the hello example which actually does something.

    For convenience here’s the source code of examples/hello.rs:

    1. //! Prints "Hello, world!" on the host console using semihosting
    3. #![no_main]
    7. use cortex_m_rt::entry;
    8. use cortex_m_semihosting::{debug, hprintln};
    10. #[entry]
    11. fn main() -> ! {
    12.     hprintln!("Hello, world!").unwrap();
    14.     // exit QEMU
    15.     // NOTE do not run this on hardware; it can corrupt OpenOCD state
    16.     debug::exit(debug::EXIT_SUCCESS);
    18.     loop {}
    19. }

    This program uses something called semihosting to print text to the host console. When using real hardware this requires a debug session but when using QEMU this Just Works.

    Let’s start by compiling the example:

    1. cargo build --example hello

    The output binary will be located at target/thumbv7m-none-eabi/debug/examples/hello.

    To run this binary on QEMU run the following command:

    1. qemu-system-arm \
    2.   -cpu cortex-m3 \
    3.   -machine lm3s6965evb \
    4.   -nographic \
    5.   -semihosting-config enable=on,target=native \
    6.   -kernel target/thumbv7m-none-eabi/debug/examples/hello
    1. Hello, world!

    The command should successfully exit (exit code = 0) after printing the text. On *nix you can check that with the following command:

    1. echo $?
    1. 0

    Let’s break down that QEMU command:

    • qemu-system-arm. This is the QEMU emulator. There are a few variants of these QEMU binaries; this one does full system emulation of ARM machines hence the name.

    • -cpu cortex-m3. This tells QEMU to emulate a Cortex-M3 CPU. Specifying the CPU model lets us catch some miscompilation errors: for example, running a program compiled for the Cortex-M4F, which has a hardware FPU, will make QEMU error during its execution.

    • -machine lm3s6965evb. This tells QEMU to emulate the LM3S6965EVB, a evaluation board that contains a LM3S6965 microcontroller.

    • -nographic. This tells QEMU to not launch its GUI.

    • -semihosting-config (..). This tells QEMU to enable semihosting. Semihosting lets the emulated device, among other things, use the host stdout, stderr and stdin and create files on the host.

    • -kernel $file. This tells QEMU which binary to load and run on the emulated machine.

    Typing out that long QEMU command is too much work! We can set a custom runner to simplify the process. .cargo/config.toml has a commented out runner that invokes QEMU; let’s uncomment it:

    1. head -n3 .cargo/config.toml
    1. [target.thumbv7m-none-eabi]
    2. # uncomment this to make `cargo run` execute programs on QEMU
    3. runner = "qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel"

    This runner only applies to the thumbv7m-none-eabi target, which is our default compilation target. Now cargo run will compile the program and run it on QEMU:

    1. cargo run --example hello --release
    1.    Compiling app v0.1.0 (file:///tmp/app)
    2.     Finished release [optimized + debuginfo] target(s) in 0.26s
    3.      Running `qemu-system-arm -cpu cortex-m3 -machine lm3s6965evb -nographic -semihosting-config enable=on,target=native -kernel target/thumbv7m-none-eabi/release/examples/hello`
    4. Hello, world!

    Debugging

    Debugging an embedded device involves remote debugging as the program that we want to debug won’t be running on the machine that’s running the debugger program (GDB or LLDB).

    Remote debugging involves a client and a server. In a QEMU setup, the client will be a GDB (or LLDB) process and the server will be the QEMU process that’s also running the embedded program.

    In this section we’ll use the hello example we already compiled.

    The first debugging step is to launch QEMU in debugging mode:

    This command won’t print anything to the console and will block the terminal. We have passed two extra flags this time:

    • -gdb tcp::3333. This tells QEMU to wait for a GDB connection on TCP port 3333.

    • -S. This tells QEMU to freeze the machine at startup. Without this the program would have reached the end of main before we had a chance to launch the debugger!

    Next we launch GDB in another terminal and tell it to load the debug symbols of the example:

    1. gdb-multiarch -q target/thumbv7m-none-eabi/debug/examples/hello

    NOTE: you might need another version of gdb instead of gdb-multiarch depending on which one you installed in the installation chapter. This could also be arm-none-eabi-gdb or just gdb.

    Then within the GDB shell we connect to QEMU, which is waiting for a connection on TCP port 3333.

    1. target remote :3333
    1. Remote debugging using :3333
    2. Reset () at $REGISTRY/cortex-m-rt-0.6.1/src/lib.rs:473
    3. 473     pub unsafe extern "C" fn Reset() -> ! {

    You’ll see that the process is halted and that the program counter is pointing to a function named Reset. That is the reset handler: what Cortex-M cores execute upon booting.

    This reset handler will eventually call our main function. Let’s skip all the way there using a breakpoint and the continue command. To set the breakpoint, let’s first take a look where we would like to break in our code, with the list command.

    1. list main

    This will show the source code, from the file examples/hello.rs.

    1. 6       use panic_halt as _;
    2. 7
    3. 8       use cortex_m_rt::entry;
    4. 9       use cortex_m_semihosting::{debug, hprintln};
    5. 10
    6. 11      #[entry]
    7. 12      fn main() -> ! {
    8. 13          hprintln!("Hello, world!").unwrap();
    9. 14
    10. 15          // exit QEMU

    We would like to add a breakpoint just before the “Hello, world!”, which is on line 13. We do that with the break command:

    1. break 13

    We can now instruct gdb to run up to our main function, with the continue command:

    1. continue
    1. Continuing.
    3. Breakpoint 1, hello::__cortex_m_rt_main () at examples\hello.rs:13
    4. 13          hprintln!("Hello, world!").unwrap();

    We are now close to the code that prints “Hello, world!”. Let’s move forward using the next command.

    1. next
    1. 16          debug::exit(debug::EXIT_SUCCESS);

    At this point you should see “Hello, world!” printed on the terminal that’s running qemu-system-arm.

    1. $ qemu-system-arm (..)
    2. Hello, world!

    Calling next again will terminate the QEMU process.

    1. [Inferior 1 (Remote target) exited normally]

    You can now exit the GDB session.