From f021723eb744313db8878aa8de5282d7ab182871 Mon Sep 17 00:00:00 2001 From: Berthier Lemieux Date: Sun, 17 May 2020 10:13:42 +0300 Subject: [PATCH 1/2] QEMU debugging updates --- src/intro/install/verify.md | 2 +- src/intro/install/windows.md | 12 ++++---- src/start/qemu.md | 54 ++++++++++++++++++++++++------------ 3 files changed, 43 insertions(+), 25 deletions(-) diff --git a/src/intro/install/verify.md b/src/intro/install/verify.md index ad58c003..2b114ffb 100644 --- a/src/intro/install/verify.md +++ b/src/intro/install/verify.md @@ -17,7 +17,7 @@ ST-LINK header is circled in red. Now run the following command: ``` console -$ openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg +$ openocd -f interface/stlink.cfg -f target/stm32f3x.cfg ``` You should get the following output and the program should block the console: diff --git a/src/intro/install/windows.md b/src/intro/install/windows.md index a055b00c..374f379b 100644 --- a/src/intro/install/windows.md +++ b/src/intro/install/windows.md @@ -16,13 +16,13 @@ GNU gdb (GNU Tools for Arm Embedded Processors 7-2018-q2-update) 8.1.0.20180315- ## OpenOCD -There's no official binary release of OpenOCD for Windows but there are unofficial releases -available [here][openocd]. Grab the 0.10.x zipfile and extract it somewhere on your drive (I -recommend `C:\OpenOCD` but with the drive letter that makes sense to you) then update your `%PATH%` -environment variable to include the following path: `C:\OpenOCD\bin` (or the path that you used -before). +There's no official binary release of OpenOCD for Windows but if you're not in the mood to compile +it yourself, the xPack project provides a binary distribution, [here][openocd]. Follow the +provided installation instructions. Then update your `%PATH%` environment variable to +include the path where the binaries were installed. (`C:\Users\USERNAME\AppData\Roaming\xPacks\@xpack-dev-tools\openocd\0.10.0-13.1\.content\bin\`, +if you've been using the easy install) -[openocd]: https://github.com/gnu-mcu-eclipse/openocd/releases +[openocd]: https://xpack.github.io/openocd/ Verify that OpenOCD is in your `%PATH%` with: diff --git a/src/start/qemu.md b/src/start/qemu.md index f032a2eb..7f2e580e 100644 --- a/src/start/qemu.md +++ b/src/start/qemu.md @@ -16,7 +16,10 @@ substitutions. ## Creating a non standard Rust program We'll use the [`cortex-m-quickstart`] project template to generate a new -project from it. +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 `examples` directory, with several separate applications, highlighting +some of the key embedded rust functionality. [`cortex-m-quickstart`]: https://github.com/rust-embedded/cortex-m-quickstart @@ -151,8 +154,14 @@ target = "thumbv7m-none-eabi" # Cortex-M3 ``` To cross compile for the Cortex-M3 architecture we have to use -`thumbv7m-none-eabi`. This compilation target has been set as the default so the -two commands below do the same: +`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: +``` console +$ rustup target add thumbv7m-none-eabi +``` + Since the `thumbv7m-none-eabi` compilation target has been set as the default in + your `.cargo/config` file, the two commands below do the same: ```console cargo build --target thumbv7m-none-eabi @@ -201,8 +210,6 @@ ELF Header: `cargo-size` can print the size of the linker sections of the binary. -> **NOTE** this output assumes that rust-embedded/cortex-m-rt#111 has been -> merged ```console cargo size --bin app --release -- -A @@ -433,6 +440,26 @@ also running the embedded program. In this section we'll use the `hello` example we already compiled. +Before getting started remotely debugging our app running in QEMU with GDB, +let's modify our app configuration `.cargo/config`, to enable the GNU ARM linker: + +```toml +... +rustflags = [ + # LLD (shipped with the Rust toolchain) is used as the default linker + #"-C", "link-arg=-Tlink.x", <--- Comment this line + + # if you run into problems with LLD switch to the GNU linker by commenting out + # this line + "-C", "linker=arm-none-eabi-ld", #<--- Uncomment this line +``` +We do that, as the default linker (LLD) doesn't always play nice with the GNU ARM GDB. +Rebuild the application. + +```console +cargo build --example hello +``` + The first debugging step is to launch QEMU in debugging mode: ```console @@ -488,11 +515,11 @@ This reset handler will eventually call our main function. Let's skip all the way there using a breakpoint and the `continue` command: ```console -break main +break hello::__cortex_m_rt_main ``` ```text -Breakpoint 1 at 0x400: file examples/panic.rs, line 29. +Breakpoint 1 at 0x410: file examples\hello.rs, line 13. ``` ```console @@ -502,8 +529,8 @@ continue ```text Continuing. -Breakpoint 1, main () at examples/hello.rs:17 -17 let mut stdout = hio::hstdout().unwrap(); +Breakpoint 1, hello::__cortex_m_rt_main () at examples\hello.rs:13 +13 hprintln!("Hello, world!").unwrap(); ``` We are now close to the code that prints "Hello, world!". Let's move forward @@ -512,15 +539,6 @@ using the `next` command. ``` console next ``` - -```text -18 writeln!(stdout, "Hello, world!").unwrap(); -``` - -```console -next -``` - ```text 20 debug::exit(debug::EXIT_SUCCESS); ``` From 9f59ab8f74cbe808978f857ba013d8cc85ba12f2 Mon Sep 17 00:00:00 2001 From: Berthier Lemieux Date: Tue, 19 May 2020 21:22:51 +0300 Subject: [PATCH 2/2] Revert to recommand using LLD, mentionning the possible mixed-up debuginfo. --- src/start/qemu.md | 54 ++++++++++++++++++++++++++--------------------- 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/src/start/qemu.md b/src/start/qemu.md index 7f2e580e..50a70224 100644 --- a/src/start/qemu.md +++ b/src/start/qemu.md @@ -440,26 +440,6 @@ also running the embedded program. In this section we'll use the `hello` example we already compiled. -Before getting started remotely debugging our app running in QEMU with GDB, -let's modify our app configuration `.cargo/config`, to enable the GNU ARM linker: - -```toml -... -rustflags = [ - # LLD (shipped with the Rust toolchain) is used as the default linker - #"-C", "link-arg=-Tlink.x", <--- Comment this line - - # if you run into problems with LLD switch to the GNU linker by commenting out - # this line - "-C", "linker=arm-none-eabi-ld", #<--- Uncomment this line -``` -We do that, as the default linker (LLD) doesn't always play nice with the GNU ARM GDB. -Rebuild the application. - -```console -cargo build --example hello -``` - The first debugging step is to launch QEMU in debugging mode: ```console @@ -507,20 +487,45 @@ Reset () at $REGISTRY/cortex-m-rt-0.6.1/src/lib.rs:473 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. +> Note that on some setup, instead of displaying the line `Reset () at $REGISTRY/cortex-m-rt-0.6.1/src/lib.rs:473` as shown above, gdb may print some warnings like : +> +>`core::num::bignum::Big32x40::mul_small () at src/libcore/num/bignum.rs:254` +> ` src/libcore/num/bignum.rs: No such file or directory.` +> +> That's a known glitch. You can safely ignore those warnings, you're most likely at Reset(). + + This reset handler will eventually call our main function. Let's skip all the -way there using a breakpoint and the `continue` command: +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. ```console -break hello::__cortex_m_rt_main +list main ``` +This will show the source code, from the file examples/hello.rs. ```text -Breakpoint 1 at 0x410: file examples\hello.rs, line 13. +6 extern crate panic_halt; +7 +8 use cortex_m_rt::entry; +9 use cortex_m_semihosting::{debug, hprintln}; +10 +11 #[entry] +12 fn main() -> ! { +13 hprintln!("Hello, world!").unwrap(); +14 +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: + +```console +break 13 +``` +We can now instruct gdb to run up to our main function, with the `continue` command: ```console continue @@ -539,8 +544,9 @@ using the `next` command. ``` console next ``` + ```text -20 debug::exit(debug::EXIT_SUCCESS); +16 debug::exit(debug::EXIT_SUCCESS); ``` At this point you should see "Hello, world!" printed on the terminal that's