Merge #305

305: Update 05 led-roulette r=therealprof a=winksaville

Cargo.toml to use stm32f3-discovery v0.6.0 crate.

Update `.md` files with additional information and to make console
commands amenable to copy/paste operations.

Co-authored-by: Wink Saville <wink@saville.com>

Author: bors[bot]

src/05-led-roulette/README.md

@@ -44,6 +44,7 @@ point function must have signature `fn() -> !`; this type indicates that the fun
 If you are a careful observer, you'll also notice there is a `.cargo` directory in the Cargo project
 as well. This directory contains a Cargo configuration file (`.cargo/config`) that tweaks the
 linking process to tailor the memory layout of the program to the requirements of the target device.
-This modified linking process is a requirement of the `cortex-m-rt` crate.
+This modified linking process is a requirement of the `cortex-m-rt` crate. You'll also be making
+further tweaks to `.cargo/config` in future sections to make building and debugging easier.
 
 Alright, let's start by building this program.

src/05-led-roulette/auxiliary/Cargo.toml

@@ -11,6 +11,6 @@ version = "0.2.0"
 [dependencies]
 cortex-m = "0.6.4"
 cortex-m-rt = "0.6.13"
-stm32f3-discovery = "0.5.0"
+stm32f3-discovery = "0.6.0"
 panic-halt = "0.2.0"
 panic-itm = "0.4.2"

src/05-led-roulette/build-it.md

@@ -19,41 +19,89 @@ download pre-compiled version of the standard library (a reduced version of it a
 target. That's done using `rustup`:
 
 ``` console
-$ rustup target add thumbv7em-none-eabihf
+rustup target add thumbv7em-none-eabihf
 ```
 
 You only need to do the above step once; `rustup` will re-install a new standard library
 (`rust-std` component) whenever you update your toolchain.
 
-With the `rust-std` component in place you can now cross compile the program using Cargo:
+With the `rust-std` component in place you can now cross compile the program using Cargo.
 
+> Note: make sure you are in the `src/05-led-roulette` directory
+> and run `cargo build` command below to create the executable:
+``` console
+cargo build --target thumbv7em-none-eabihf
+```
+On your console you should see something like:
 ``` console
-$ # make sure you are in the `src/05-led-roulette` directory
-
 $ cargo build --target thumbv7em-none-eabihf
    Compiling typenum v1.12.0
    Compiling semver-parser v0.7.0
    Compiling version_check v0.9.2
-   Compiling cortex-m v0.6.4
+   Compiling nb v1.0.0
+   Compiling void v1.0.2
+   Compiling autocfg v1.0.1
+   Compiling cortex-m v0.7.1
+   Compiling proc-macro2 v1.0.24
+   Compiling vcell v0.1.3
+   Compiling unicode-xid v0.2.1
+   Compiling stable_deref_trait v1.2.0
+   Compiling syn v1.0.60
+   Compiling bitfield v0.13.2
+   Compiling cortex-m v0.6.7
    Compiling cortex-m-rt v0.6.13
-   Compiling stm32f3-discovery v0.5.0
-   ...
+   Compiling r0 v0.2.2
+   Compiling stm32-usbd v0.5.1
+   Compiling stm32f3 v0.12.1
+   Compiling usb-device v0.2.7
+   Compiling cfg-if v1.0.0
+   Compiling paste v1.0.4
+   Compiling stm32f3-discovery v0.6.0
+   Compiling panic-halt v0.2.0
+   Compiling embedded-dma v0.1.2
+   Compiling volatile-register v0.2.0
+   Compiling nb v0.1.3
+   Compiling embedded-hal v0.2.4
+   Compiling semver v0.9.0
+   Compiling generic-array v0.14.4
+   Compiling switch-hal v0.3.2
+   Compiling num-traits v0.2.14
+   Compiling num-integer v0.1.44
+   Compiling rustc_version v0.2.3
+   Compiling bare-metal v0.2.5
+   Compiling cast v0.2.3
+   Compiling quote v1.0.9
+   Compiling generic-array v0.13.2
+   Compiling generic-array v0.12.3
+   Compiling generic-array v0.11.1
    Compiling panic-itm v0.4.2
+   Compiling lsm303dlhc v0.2.0
+   Compiling as-slice v0.1.4
+   Compiling micromath v1.1.0
+   Compiling accelerometer v0.12.0
+   Compiling chrono v0.4.19
+   Compiling aligned v0.3.4
+   Compiling rtcc v0.2.0
    Compiling cortex-m-rt-macros v0.1.8
-   Compiling stm32f3xx-hal v0.5.0
-   Compiling aux5 v0.2.0 (file://$PWD/auxiliary)
-   Compiling led-roulette v0.2.0 (file://$PWD/)
-    Finished dev [unoptimized + debuginfo] target(s) in 19.45s
+   Compiling stm32f3xx-hal v0.6.1
+   Compiling aux5 v0.2.0 (~/embedded-discovery/src/05-led-roulette/auxiliary)
+   Compiling led-roulette v0.2.0 (~/embedded-discovery/src/05-led-roulette)
+    Finished dev [unoptimized + debuginfo] target(s) in 17.91s
 ```
 
 > **NOTE** Be sure to compile this crate *without* optimizations. The provided Cargo.toml file and build command above will ensure optimizations are off. 
 
 OK, now we have produced an executable. This executable won't blink any leds, it's just a simplified version that we will build upon later in the chapter. As a sanity check, let's verify that the produced executable is actually an ARM binary:
 
 ``` console
-$ # equivalent to `readelf -h target/thumbv7em-none-eabihf/debug/led-roulette`
-$ cargo readobj --target thumbv7em-none-eabihf --bin led-roulette -- -file-headers
-    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
+cargo readobj --target thumbv7em-none-eabihf --bin led-roulette -- --file-header
+```
+The `cargo readobj ..` above is equivalent to
+`readelf -h target/thumbv7em-none-eabihf/debug/led-roulette`
+and should produce something similar to:
+``` console
+$ cargo readobj --target thumbv7em-none-eabihf --bin led-roulette -- --file-header
+    Finished dev [unoptimized + debuginfo] target(s) in 0.02s
 ELF Header:
   Magic:   7f 45 4c 46 01 01 01 00 00 00 00 00 00 00 00 00
   Class:                             ELF32
@@ -66,7 +114,7 @@ ELF Header:
   Version:                           0x1
   Entry point address:               0x8000195
   Start of program headers:          52 (bytes into file)
-  Start of section headers:          797192 (bytes into file)
+  Start of section headers:          818328 (bytes into file)
   Flags:                             0x5000400
   Size of this header:               52 (bytes)
   Size of program headers:           32 (bytes)

src/05-led-roulette/debug-it.md

@@ -8,13 +8,32 @@ processor / CPU will execute first.
 
 The starter project I've provided to you has some extra code that runs *before* the `main` function.
 At this time, we are not interested in that "pre-main" part so let's skip right to the beginning of
-the `main` function. We'll do that using a breakpoint:
-
+the `main` function. We'll do that using a breakpoint. Issue `break main` at the `(gdb)` prompt:
+
+> **Note** for these gdb commands I generally won't provide a copyable code block
+> as these are short and it's faster just to type them yourself. In addition most
+> can be shortend. For instance `b` for `break` or `s` for `step`, see [gdb quick ref]
+> for more info or use Google to find your others. In addition, you can use tab completion
+> by typing the first few letters than one tab to complete or two tabs to
+> see all possible commands.
+>
+>> Finally, `help xxxx` where xxxx is the comand will provide short names and other info:
+>> ```
+>> (gdb) help s
+>> step, s
+>> Step program until it reaches a different source line.
+>> Usage: step [N]
+>> Argument N means step N times (or till program stops for another reason).
+>> ```
+
+[gdb quick ref]: https://users.ece.utexas.edu/~adnan/gdb-refcard.pdf
 ```
 (gdb) break main
 Breakpoint 1 at 0x80001f0: file src/05-led-roulette/src/main.rs, line 7.
 Note: automatically using hardware breakpoints for read-only addresses.
-
+```
+Next issue a `continue` command:
+```
 (gdb) continue
 Continuing.
 
@@ -57,9 +76,9 @@ led_roulette::__cortex_m_rt_main () at src/05-led-roulette/src/main.rs:10
 Next we'll issue a second `step` which executes line 10 and stops at
 line `11    _y = x;`, again line 11 is **not** executed.
 
-> **Note** we could have pressed enter at the second `<gdb> ` prompt and
-> it would have reissued the previous statement, `step`, but for clarity in this tutorial
-> we'll generally retype the command.
+> **Note** we could have pressed enter at the second `(gdb) ` prompt and
+> it would have reissued the previous statement, `step`, but for clarity
+> in this tutorial we'll generally retype the command.
 
 ```
 (gdb) step
@@ -71,16 +90,17 @@ along with its line number. As you'll see later in the TUI mode you'll not the s
 in the command area.
 
 We are now "on" the `_y = x` statement; that statement hasn't been executed yet. This means that `x`
-is initialized but `_y` is not. Let's inspect those stack/local variables using the `print` command:
+is initialized but `_y` is not. Let's inspect those stack/local variables using the `print`
+command, `p` for short:
 
 ```
 (gdb) print x
 $1 = 42
-(gdb) print &x
+(gdb) p &x
 $2 = (*mut i32) 0x20009fe0
-(gdb) print _y
+(gdb) p _y
 $3 = 536870912
-(gdb) print &_y
+(gdb) p &_y
 $4 = (*mut i32) 0x20009fe4
 ```
 
@@ -154,15 +174,15 @@ See the fat arrow `=>` on the left side? It shows the instruction the processor
 
 Also, as mentioned above if you were to execute the `step` command GDB gets stuck because it
 is executing a branch instruction to itself and never gets past it. So you need to use
-`Ctrl+C` to regain control. An alternative is to use the `stepi` GDB command, which steps
+`Ctrl+C` to regain control. An alternative is to use the `stepi`(`si`) GDB command, which steps
 one asm instruction, and GDB will print the address **and** line number of the statement
 the processor will execute next and it won't get stuck.
 
 ```
 (gdb) stepi
 0x08000194      14          loop {}
 
-(gdb) stepi
+(gdb) si
 0x08000194      14          loop {}
 ```
 
@@ -233,35 +253,40 @@ mode enter one of the following commands in the GDB shell:
 > **NOTE** Apologies to Windows users, the GDB shipped with the GNU ARM Embedded Toolchain
 > may not support this TUI mode `:-(`.
 
-Below is an example of setting up for a layout split by executing the follow commands:
+Below is an example of setting up for a `layout split` by executing the follow commands:
 
 ``` console
 $ cargo run --target thumbv7em-none-eabihf
-<gdb> target remote :3333
-<gdb> load
-<gdb> set print asm-demangle on
-<gdb> set style sources off
-<gdb> break main
-<gdb> continue
-<gdb> layout split
+(gdb) target remote :3333
+(gdb) load
+(gdb) set print asm-demangle on
+(gdb) set style sources off
+(gdb) break main
+(gdb) continue
 ```
 
-And below the result after `layout split` command is executed:
+Here is a command line with the above commands as `-ex` parameters to save you some typing:
+
+```
+cargo run --target thumbv7em-none-eabihf -- -q -ex 'target remote :3333' -ex 'load' -ex 'set print asm-demangle on' -ex 'set style sources off' -ex 'b main' -ex 'c' target/thumbv7em-none-eabihf/debug/led-roulette
+```
+
+And below is the result:
 
 ![GDB session layout split](../assets/gdb-layout-split-1.png "GDB TUI layout split 1")
 
-Now we'll scroll the top source window down so we see the entire file and execute `step`:
+Now we'll scroll the top source window down so we see the entire file and execute `layout split` and then `step`:
 
 ![GDB session layout split](../assets/gdb-layout-split-2.png "GDB TUI layout split 2")
 
 Then we'll execute a few `info locals` and `step`'s:
 
 ``` console
-<gdb> info locals
-<gdb> step
-<gdb> info locals
-<gdb> step
-<gdb> info locals
+(gdb) info locals
+(gdb) step
+(gdb) info locals
+(gdb) step
+(gdb) info locals
 ```
 
 ![GDB session layout split](../assets/gdb-layout-split-3.png "GDB TUI layout split 3")