Merge #299

299: New-06-hello-world r=eldruin a=winksaville Converted lib.rs, Cargo.toml to use stm32f3_discovery. .cargo/config: I also, found that I would forget to to use `--target` when building and running using cargo so set the default build target to thumbv7em-none-eabihf openocd.cfg: Since the monitor lines are quite long and also easy to mistype or forget to do I enhanced the file with the new lines and commented on each of the lines. README.md Update to reflect the above changes. Co-authored-by: Wink Saville <wink@saville.com>
rust-embedded · Feb 9, 2021 · 40a6309 · 40a6309
2 parents 79ed05f + af8bb1a
commit 40a6309
Show file tree

Hide file tree

Showing 7 changed files with 230 additions and 97 deletions.
diff --git a/src/06-hello-world/.cargo/config b/src/06-hello-world/.cargo/config
@@ -3,3 +3,6 @@ runner = "arm-none-eabi-gdb -q -x openocd.gdb"
 rustflags = [
   "-C", "link-arg=-Tlink.x",
 ]
+
+[build]
+target = "thumbv7em-none-eabihf"
diff --git a/src/06-hello-world/Cargo.toml b/src/06-hello-world/Cargo.toml
@@ -1,8 +1,11 @@
 [package]
-authors = ["Jorge Aparicio <jorge@japaric.io>"]
+authors = [
+    "Jorge Aparicio <jorge@japaric.io>",
+    "Wink Saville <wink@saville.com",
+]
 edition = "2018"
 name = "hello-world"
-version = "0.1.0"
+version = "0.2.0"
 
 [dependencies]
 aux6 = { path = "auxiliary" }
diff --git a/src/06-hello-world/README.md b/src/06-hello-world/README.md
@@ -70,73 +70,126 @@ $ itmdump -F -f itm.txt
 
 This command will block as `itmdump` is now watching the `itm.txt` file. Leave this terminal open.
 
-Make sure that F3 is connected to your computer. Open another terminal from `/tmp` directory (on Windows `%TEMP%`) to launch OpenOCD similar as described in chapter [First OpenOCD connection].
-
+Make sure that the STM32F3DISCOVERY board is connected to your computer. Open another terminal
+from `/tmp` directory (on Windows `%TEMP%`) to launch OpenOCD similar as described in chapter
 [First OpenOCD connection]: ../03-setup/verify.html#first-openocd-connection
 
 Alright. Now, let's build the starter code and flash it into the microcontroller.
 
-To avoid passing the `--target thumbv7em-none-eabihf` flag to every Cargo invocation we can set a
-default target in .cargo/config:
+To avoid passing the `--target thumbv7em-none-eabihf` flag to every Cargo invocation we
+have added `[build]` with a default target, `target = "thumbv7em-none-eabihf"`, to .cargo/config.
+Now if `--target` is not specified `cargo` will assume that the target is `thumbv7em-none-eabihf`.
+
+```
+[target.thumbv7em-none-eabihf]
+runner = "arm-none-eabi-gdb -q -x openocd.gdb"
+rustflags = [
+  "-C", "link-arg=-Tlink.x",
+]
+
+[build]
+target = "thumbv7em-none-eabihf"
+```
+
+In addition, our `opendocd.gdb` has some additional lines. Compared to the previous
+section `set`'s and initialize `monitor`ing so `iprint!` and `iprintln!`
+macros work and output is visible on a console. Below the contents with comments:
+
+``` console
+$ cat openocd.gdb
+# Connect to gdb remote server
+target remote :3333
+
+# Load will flash the code
+load
+
+# Eanble demangling asm names on disassembly
+set print asm-demangle on
+
+# Enable pretty printing
+set print pretty on
 
-``` diff
- [target.thumbv7em-none-eabihf]
- runner = "arm-none-eabi-gdb -q -x openocd.gdb"
- rustflags = [
-   "-C", "link-arg=-Tlink.x",
- ]
+# Disable style sources as the default colors can be hard to read
+set style sources off
 
-+[build]
-+target = "thumbv7em-none-eabihf"
+# Have the tpiu send the data to a file itm.txt
+monitor tpiu config internal itm.txt uart off 8000000
+
+# Turn on the itm port
+monitor itm port 0 on
+
+# Set a breakpoint at main
+break main
+
+# Continue running and we'll hit the main breakpoint
+continue
 ```
 
-Now if `--target` is not specified Cargo will assume that the target is `thumbv7em-none-eabihf`.
+We will now run the application and single step through it. Since we've added
+the `monitor` commands in `openocd.gdb` OpenOCD will redirect the ITM output to
+itm.txt and `itmdump` will write it to its terminal window.
 
 ``` console
 $ cargo run
-Reading symbols from target/thumbv7em-none-eabihf/debug/hello-world...done.
-(..)
-Loading section .vector_table, size 0x400 lma 0x8000000
-Loading section .text, size 0x27c4 lma 0x8000400
-Loading section .rodata, size 0x744 lma 0x8002be0
-Start address 0x8002980, load size 13064
-Transfer rate: 18 KB/sec, 4354 bytes/write.
-Breakpoint 1 at 0x8000402: file src/06-hello-world/src/main.rs, line 10.
+    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
+     Running `arm-none-eabi-gdb -q -x openocd.gdb ~/prgs/rust/tutorial/embedded-discovery/target/thumbv7em-none-eabihf/debug/hello-world`
+Reading symbols from ~/prgs/rust/tutorial/embedded-discovery/target/thumbv7em-none-eabihf/debug/hello-world...
+0x00000000 in ?? ()
+Loading section .vector_table, size 0x194 lma 0x8000000
+Loading section .text, size 0x28d8 lma 0x8000194
+Loading section .rodata, size 0x6b8 lma 0x8002a6c
+Start address 0x08000194, load size 12580
+Transfer rate: 18 KB/sec, 4193 bytes/write.
+Breakpoint 1 at 0x80001f0: file src/06-hello-world/src/main.rs, line 8.
 Note: automatically using hardware breakpoints for read-only addresses.
 
-Breakpoint 1, main () at src/06-hello-world/src/main.rs:10
-10          let mut itm = aux6::init();
+Breakpoint 1, hello_world::__cortex_m_rt_main_trampoline () at src/06-hello-world/src/main.rs:8
+8       #[entry]
 ```
 
-Note that there's a `openocd.gdb` at the root of the Cargo project. It's pretty similar to the one we
-used in the previous section.
-
-Before we execute the `iprintln!` statement. We have to instruct OpenOCD to redirect the ITM output
-into the same file that `itmdump` is watching.
+We are now stopped at `#[entry]` and since, as before, it's a trampoline:
 
+``` console
+(gdb) disassemble /m
+Dump of assembler code for function main:
+8	#[entry]
+   0x080001ec <+0>:	push	{r7, lr}
+   0x080001ee <+2>:	mov	r7, sp
+=> 0x080001f0 <+4>:	bl	0x80001f6 <hello_world::__cortex_m_rt_main>
+   0x080001f4 <+8>:	udf	#254	; 0xfe
 ```
-(gdb) # globally enable the ITM and redirect all output to itm.txt
-(gdb) monitor tpiu config internal itm.txt uart off 8000000
 
-(gdb) # enable the ITM port 0
-(gdb) monitor itm port 0 on
+We need to initially `step` into the main function which will position us at line 10:
+
+``` text
+(gdb) step
+hello_world::__cortex_m_rt_main () at src/06-hello-world/src/main.rs:10
+10	    let mut itm = aux6::init();
 ```
 
-All should be ready! Now execute the `iprintln!` statement.
+Now issue a `next` command which will exectue `aux6::init()` and
+stop at he next executable statement in `main.rs`, which
+positions us at line 12:
 
-```
+``` text
 (gdb) next
-12          iprintln!(&mut itm.stim[0], "Hello, world!");
+12	    iprintln!(&mut itm.stim[0], "Hello, world!");
+```
+
+Then issue another `next` command which will execute
+line 12, executing the `iprintln` and stop at line 14:
 
+``` text
 (gdb) next
-14          loop {}
+14	    loop {}
 ```
 
-You should see some output in the `itmdump` terminal:
+Now since `iprintln` has been executed the output on the `itmdump`
+terminal window should be the `Hello, world!` string:
 
 ``` console
 $ itmdump -F -f itm.txt
-(..)
+(...)
 Hello, world!
 ```
 

diff --git a/src/06-hello-world/auxiliary/Cargo.toml b/src/06-hello-world/auxiliary/Cargo.toml
@@ -1,11 +1,15 @@
 [package]
-authors = ["Jorge Aparicio <jorge@japaric.io>"]
+authors = [
+    "Jorge Aparicio <jorge@japaric.io>",
+    "Wink Saville <wink@saville.com",
+]
 edition = "2018"
 name = "aux6"
-version = "0.1.0"
+version = "0.2.0"
 
 [dependencies]
-cortex-m = "0.6.3"
-cortex-m-rt = "0.6.3"
-panic-itm = "0.4.0"
-f3 = "0.6.1"
+cortex-m = "0.6.4"
+cortex-m-rt = "0.6.13"
+stm32f3-discovery = "0.5.0"
+panic-halt = "0.2.0"
+panic-itm = "0.4.2"
diff --git a/src/06-hello-world/auxiliary/src/lib.rs b/src/06-hello-world/auxiliary/src/lib.rs
@@ -2,14 +2,16 @@
 
 #![no_std]
 
-#[allow(unused_extern_crates)] // NOTE(allow) bug rust-lang/rust#53964
-extern crate f3; // provides memory.x
-#[allow(unused_extern_crates)] // NOTE(allow) bug rust-lang/rust#53964
-extern crate panic_itm; // panic handler
+pub use panic_itm;
 
-pub use cortex_m::{asm::bkpt, iprint, iprintln, peripheral::ITM};
 pub use cortex_m_rt::entry;
 
+// Need stm32f3xx_hal::prelude::* otherwise
+//   'Error(corex-m-rt): The interrupt vectors are missing`
+pub use stm32f3_discovery::stm32f3xx_hal::prelude::*;
+
+pub use cortex_m::{asm::bkpt, iprint, iprintln, peripheral::ITM};
+
 pub fn init() -> ITM {
     let p = cortex_m::Peripherals::take().unwrap();
 

diff --git a/src/06-hello-world/openocd.gdb b/src/06-hello-world/openocd.gdb
@@ -1,6 +1,26 @@
+# Connect to gdb remote server
 target remote :3333
+
+# Load will flash the code
+load
+
+# Eanble demangling asm names on disassembly
 set print asm-demangle on
+
+# Enable pretty printing
 set print pretty on
-load
+
+# Disable style sources as the default colors can be hard to read
+set style sources off
+
+# Have the tpiu send the data to a file tim.txt
+monitor tpiu config internal itm.txt uart off 8000000
+
+# Turn on the itm port
+monitor itm port 0 on
+
+# Set a breakpoint at main
 break main
+
+# Continue running and we'll hit the main breakpoint
 continue