Merge #332

332: Fix some flaws in the "LED roulette" section r=adamgreig a=SimplyDanny



Co-authored-by: Danny Moesch <danny.moesch@icloud.com>

Author: bors[bot]

src/05-led-roulette/README.md

@@ -36,8 +36,8 @@ The `no_main` attribute says that this program won't use the standard `main` int
 tailored for command line applications that receive arguments. Instead of the standard `main` we'll
 use the `entry` attribute from the [`cortex-m-rt`] crate to define a custom entry point. In this
 program we have named the entry point "main", but any other name could have been used. The entry
-point function must have signature `fn() -> !`; this type indicates that the function can't return
--- this means that the program never terminates.
+point function must have the signature `fn() -> !`; this type indicates that the function can't
+return – this means that the program never terminates.
 
 [`cortex-m-rt`]: https://crates.io/crates/cortex-m-rt
 

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

@@ -15,7 +15,7 @@ families within that architecture:
 - `thumbv7em-none-eabihf`, for the Cortex-M4**F** and Cortex-M7**F** processors
 
 For the F3, we'll use the `thumbv7em-none-eabihf` target. Before cross compiling you have to
-download pre-compiled version of the standard library (a reduced version of it actually) for your
+download a pre-compiled version of the standard library (a reduced version of it actually) for your
 target. That's done using `rustup`:
 
 ``` console
@@ -27,7 +27,7 @@ You only need to do the above step once; `rustup` will re-install a new standard
 
 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
+> **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
@@ -88,9 +88,9 @@ $ cargo build --target thumbv7em-none-eabihf
     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. 
+> **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:
+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
 cargo readobj --target thumbv7em-none-eabihf --bin led-roulette -- --file-header

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

@@ -10,9 +10,9 @@ The starter project I've provided to you has some extra code that runs *before*
 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. Issue `break main` at the `(gdb)` prompt:
 
-> **Note** for these gdb commands I generally won't provide a copyable code block
+> **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]
+> can be shortend. For instance `b` for `break` or `s` for `step`, see [GDB Quick Reference]
 > 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.
@@ -26,7 +26,7 @@ the `main` function. We'll do that using a breakpoint. Issue `break main` at the
 >> 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 Quick Reference]: 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.
@@ -49,7 +49,7 @@ which is a trampoline to the main function and where `break main` sets the break
 > breakpoints so it's a good idea to pay attention to these messages.
 
 OK. Since we are stopped at `#[entry]` and using the `disassemble /m` we see the code
-for entry, which is a trampoline to main. What that means it sets up the stack and then
+for entry, which is a trampoline to main. That means it sets up the stack and then
 invokes a subroutine call to the `main` function using an ARM branch and link instruction, `bl`.
 ```
 (gdb) disassemble /m
@@ -63,7 +63,7 @@ Dump of assembler code for function main:
 End of assembler dump.
 ```
 
-Next we need to issue a `step` gdb command which will advance the program statement
+Next we need to issue a `step` GDB command which will advance the program statement
 by statement stepping into functions/procedures. So after this first `step` command we're
 inside `main` and are positioned at the first executable `rust` statement, line 10, but it is
 **not** executed:
@@ -76,7 +76,7 @@ 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
+> **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.
 
@@ -86,7 +86,7 @@ line `11    _y = x;`, again line 11 is **not** executed.
 ```
 
 As you can see, in this mode, on each `step` command GDB will print the current statement along
-along with its line number. As you'll see later in the TUI mode you'll not the see the statement
+with its line number. As you'll see later in the TUI mode you'll not see the statement
 in the command area.
 
 We are now "on" the `_y = x` statement; that statement hasn't been executed yet. This means that `x`

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

@@ -135,16 +135,17 @@ In both failing and successful cases you should see new output in the **OpenOCD
 +Info : flash size = 256kbytes
 ```
 
-**NOTE**: If you are getting an error like `undefined debug reason 7 - target needs reset`, you can try running `monitor reset halt` as described [here](https://stackoverflow.com/questions/38994596/reason-7-target-needs-reset-unreliable-debugging-setup).
+> **NOTE** If you are getting an error like `undefined debug reason 7 - target needs reset`, you can try running `monitor reset halt` as described [here](https://stackoverflow.com/questions/38994596/reason-7-target-needs-reset-unreliable-debugging-setup).
 
 By default OpenOCD's GDB server listens on TCP port 3333 (localhost). This command is connecting to
 that port.
 
 ## Update ../.cargo/config.toml
 
 Now that you've successfully determined which debugger you need to use
-we need to change `../.cargo/config.toml` so that `cargo run` command will succeed.
-Note: `cargo` is the rust package manager and you can read about it
+we need to change `../.cargo/config.toml` so that the `cargo run` command will succeed.
+
+> **NOTE** `cargo` is the Rust package manager and you can read about it
 [here](https://doc.rust-lang.org/cargo/).
 
 Get back to the terminal prompt and look at `../.cargo/config.toml`:
@@ -190,11 +191,11 @@ index ddff17f..8512cfe 100644
 Now that you have `../.cargo/config.toml` setup let's test it using `cargo run` to
 start the debug session.
 
-> Note the `--target thumbv7em-none-eabihf` defines which architecture
+> **NOTE** The `--target thumbv7em-none-eabihf` defines which architecture
 > to build and run. In our `../.cargo/config.toml` file we have
 > `target = "thumbv7em-none-eabihf"` so it is actually not necessary
 > to specify `--target` we do it here just so you know that parameters on
-> the command line can be used and they override those in `config.toml` files
+> the command line can be used and they override those in `config.toml` files.
 
 ```
 cargo run --target thumbv7em-none-eabihf
@@ -224,7 +225,7 @@ directory.
 
 ## Flash the device
 
-Assuming you have gdb running, if not start it as suggested in the previous section.
+Assuming you have GDB running, if not start it as suggested in the previous section.
 
 Now use the `load` command in `gdb` to actually flash the program into the device:
 ```

src/05-led-roulette/the-challenge.md

@@ -26,7 +26,7 @@ entering the same commands at the beginning. We can use a `.gdb` file to execute
 right after GDB is started. This way you can save yourself the effort of having to enter them
 manually on each GDB session.
 
-As it turns out we've already created `../openocd.gdb` and you can see it's doing 
+As it turns out we've already created `../openocd.gdb` and you can see it's doing
 pretty much what we did in the previous section plus a few other commands. Look at
 the comments for additional information:
 

src/05-led-roulette/the-led-and-delay-abstractions.md

@@ -28,7 +28,7 @@ cargo build
 > session ensuring you never forget to recompile your program.
 
 Now we'll run and repeat the flashing procedure as we did in the previous section
-but with the new program. I'll let you type in the `cargo run`, *this will get easier shortly* :)
+but with the new program. I'll let you type in the `cargo run`, *this will get easier shortly*. :)
 ``` console
 $ cargo run
     Finished dev [unoptimized + debuginfo] target(s) in 0.01s
@@ -62,7 +62,7 @@ Breakpoint 1, led_roulette::__cortex_m_rt_main_trampoline ()
 led_roulette::__cortex_m_rt_main () at ~/embedded-discovery/src/05-led-roulette/src/main.rs:9
 9           let (mut delay, mut leds): (Delay, LedArray) = aux5::init();
 
-(gdb) 
+(gdb)
 ```
 
 OK. Let's step through the code. This time, we'll use the `next` command instead of `step`. The
@@ -186,7 +186,7 @@ Run till exit from #0  0x08002f80 in stm32f3xx_hal::delay::{{impl}}::delay_ms (s
 We are back in `main`. We have a local variable in here: `half_period`
 
 ```
-(gdb) print half_period 
+(gdb) print half_period
 $3 = 500
 ```
 
@@ -195,14 +195,14 @@ Now, we are going to modify this variable using the `set` command:
 ```
 (gdb) set half_period = 100
 
-(gdb) print half_period 
+(gdb) print half_period
 $5 = 100
 ```
 
 If you let program run free again using the `continue` command, you **might** see that the LED will
 blink at a much faster rate now, but more likely the blink rate didn't change. **What happened?**
 
-Let's stop the program with `Ctrl+C` and then set a break point at `main:14`. 
+Let's stop the program with `Ctrl+C` and then set a break point at `main:14`.
 ``` console
 (gdb) continue
 Continuing.