Merge #308

308: Add shareable instances of config.toml and openocd.gdb r=eldruin a=winksaville

Instead of every chapter having its own copy of the cargo configuration
and openocd.gdb files this change creates a shared set. This will make it
much easier for the user of the discovery book to handle the situation
where their Arm gdb is NOT arm-none-eabi-gdb. As only the shared copy
of .cargo/config.toml will have to be modified.

Also src/05-led-roulette is updated to take advantage of this and I
will go through each of the other chapters changing them to use
the shared set.

I also needed to comment out the rustflags variable in all of the config
files as I'd get an error executing ci/script.sh:

  ry.x:5: region 'FLASH' already defined
          >>>   FLASH : ORIGIN = 0x08000000, LENGTH = 256K
          >>>

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

src/05-led-roulette/.cargo/config → src/.cargo/config.toml

@@ -1,5 +1,11 @@
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q"
+# runner = "gdb-multiarch -q"
+# runner = "gdb -q"
 rustflags = [
   "-C", "link-arg=-Tlink.x",
 ]
+
+[build]
+target = "thumbv7em-none-eabihf"
+

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

@@ -253,10 +253,11 @@ 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.
+As you can see we've dropped passing the `--target` parameter:
 
 ``` console
-$ cargo run --target thumbv7em-none-eabihf
+$ cargo run
 (gdb) target remote :3333
 (gdb) load
 (gdb) set print asm-demangle on
@@ -265,10 +266,10 @@ $ cargo run --target thumbv7em-none-eabihf
 (gdb) continue
 ```
 
-Here is a command line with the above commands as `-ex` parameters to save you some typing:
-
+Here is a command line with the above commands as `-ex` parameters to save you some typing,
+shortly we'll be providing an easier way to execute the initial set of commands:
 ```
-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
+cargo run -- -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:

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

@@ -11,7 +11,7 @@ Onto the actual flashing. First thing we need is to do is launch OpenOCD. We did
 previous section but this time we'll run the command inside a temporary directory (`/tmp` on \*nix;
 `%TEMP%` on Windows).
 
-Make sure the F3 is connected to your computer and run the following commands on a **new terminal**.
+Make sure the F3 is connected to your computer and run the following commands in a **new terminal**.
 
 ## For *nix & MacOS:
 ``` console
@@ -85,7 +85,7 @@ I mentioned that OpenOCD provides a GDB server so let's connect to that right no
 
 ## Execute GDB
 
-First we need to determine what version of GDB you have that is capable of debugging ARM binaries.
+First, we need to determine what version of `gdb` you have that is capable of debugging ARM binaries.
 
 This could be any one of the commands below, try each one:
 ``` console
@@ -140,74 +140,87 @@ In both failing and successful cases you should see new output in the **OpenOCD
 By default OpenOCD's GDB server listens on TCP port 3333 (localhost). This command is connecting to
 that port.
 
-## Update .cargo/config
+## Update ../.cargo/config.toml
 
 Now that you've successfully determined which debugger you need to use
-we need to change `.cargo/config` so that `cargo run` command can succeed.
+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
+[here](https://doc.rust-lang.org/cargo/).
 
-Get back to the terminal prompt and looking at `.cargo/config`:
+Get back to the terminal prompt and look at `../cargo/config.toml`:
 ``` console
-$ cat .cargo/config
+~/embedded-discovery/src/05-led-roulette
+$ cat ../.cargo/config.toml
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q"
+# runner = "gdb-multiarch -q"
+# runner = "gdb -q"
 rustflags = [
   "-C", "link-arg=-Tlink.x",
 ]
 
+[build]
+target = "thumbv7em-none-eabihf"
+
 ```
-Use your favorite editor to edit `.cargo/config` so that the
-runner line contains the name of that debugger:
+Use your favorite editor to edit `../.cargo/config.toml` so that the
+`runner` line contains the correct name of that debugger:
 ``` console
-nano .cargo/config
+nano ../.cargo/config.toml
 ```
 For example, if your debugger was `gdb-multiarch` then after
-editing you should have:
-``` console
-$ cat .cargo/config
-[target.thumbv7em-none-eabihf]
-runner = "gdb-mulitarch -q"
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-]
-```
-And `git diff` should be:
+editing the `git diff` should be:
 ``` diff
-$ git diff .cargo/config
-diff --git a/src/05-led-roulette/.cargo/config b/src/05-led-roulette/.cargo/config
-index 01d25c8..c23dc80 100644
---- a/src/05-led-roulette/.cargo/config
-+++ b/src/05-led-roulette/.cargo/config
-@@ -1,5 +1,5 @@
+$ git diff ../.cargo/config.toml
+diff --git a/src/.cargo/config.toml b/src/.cargo/config.toml
+index ddff17f..8512cfe 100644
+--- a/src/.cargo/config.toml
++++ b/src/.cargo/config.toml
+@@ -1,6 +1,6 @@
  [target.thumbv7em-none-eabihf]
 -runner = "arm-none-eabi-gdb -q"
+-# runner = "gdb-multiarch -q"
++# runner = "arm-none-eabi-gdb -q"
 +runner = "gdb-multiarch -q"
+ # runner = "gdb -q"
  rustflags = [
    "-C", "link-arg=-Tlink.x",
- ]
 ```
 
-Now that you have `.cargo/config` setup to let's test it and use `cargo run` to
-start the debug session:
+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
+> 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
+
+```
+cargo run --target thumbv7em-none-eabihf
+```
+Results in:
 ```
 ~/embedded-discovery/src/05-led-roulette
 $ cargo run --target thumbv7em-none-eabihf
     Finished dev [unoptimized + debuginfo] target(s) in 0.01s
      Running `arm-none-eabi-gdb -q ~/embedded-discovery/target/thumbv7em-none-eabihf/debug/led-roulette`
 Reading symbols from ~/embedded-discovery/target/thumbv7em-none-eabihf/debug/led-roulette...
+```
 
+Now issue the `target remote :3333` to connect to the OpenOCD server
+and connect to the F3:
+```
 (gdb) target remote :3333
 Remote debugging using :3333
 0x00000000 in ?? ()
-
-(gdb)
 ```
 
-Bravo, you'll be making additional changes to `.cargo/config` in future
-sections to make building and debugging easier.
-
-> **Note** the default `.cargo/config` in every chapter assumes
-> the debugger is `arm-none-eabi-gdb`. So the first thing you should
-> do when you start a new chapter is edit `.cargo/config`!
+Bravo, we will be modifying `../.cargo/config.toml` in future. **But**, since
+this file is shared with all of the chapters those changes should be made with
+that in mind. If you want or we need to make changes that only pertain to
+a particular chapter then create a `.cargo/config.toml` local to that chapter
+directory.
 
 ## Flash the device
 

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

@@ -26,42 +26,88 @@ 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.
 
-Using an editor create `openocd.gdb` in the root of the Cargo project, right next to the `Cargo.toml`:
+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:
 
 ``` console
-nano openocd.gdb
-```
-
-And add the following text:
-
-``` text
+$ 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
+
+# Disable style sources as the default colors can be hard to read
+set style sources off
+
+# Initialize monitoring so iprintln! macro output
+# is sent from the itm port to 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, aka entry
 break main
+
+# Set a breakpiont at DefaultHandler
+break DefaultHandler
+
+# Set a breakpiont at HardFault
+break HardFault
+
+# Continue running and unill we hit the main breakpoint
 continue
+
+# Step from the trampoline code in entry into main
 step
 
 ```
 
-Next modify the `.cargo/config` file to execute openocd.gdb and we'll
-also add a `[build]` section with `thumbv7em-none-eabihf` so we don't
-have to specify the `--target` when using `cargo build` or `cargo run`:
-
+Now we need to modify the `../.cargo/config.toml` file to execute `../openocd.gdb`
 ``` console
-nano .cargo/config
+nano ../openocd.gdb
 ```
 
-Replacing the contents with the text below. This adds `-x openocd.gdb` to
-the `runner =` line and appends `[build]` and `target = "thumbv7em-none-eabihf` lines:
+Edit your `runner` command ` -x ../openocd.gdb`.
+Assuming you're using `arm-none-eabi-gdb` the diff is:
+``` diff
+~/embedded-discovery/src/05-led-roulette
+$ git diff ../.cargo/config.toml
+diff --git a/src/.cargo/config.toml b/src/.cargo/config.toml
+index ddff17f..02ac952 100644
+--- a/src/.cargo/config.toml
++++ b/src/.cargo/config.toml
+@@ -1,5 +1,5 @@
+ [target.thumbv7em-none-eabihf]
+-runner = "arm-none-eabi-gdb -q"
++runner = "arm-none-eabi-gdb -q -x ../openocd.gdb"
+ # runner = "gdb-multiarch -q"
+ # runner = "gdb -q"
+ rustflags = [
+```
+
+And the full contents of `../.cargo/config.toml`, again
+assuming `arm-none-eabi-gdb`, is:
 ``` toml
 [target.thumbv7em-none-eabihf]
-runner = "arm-none-eabi-gdb -q -x openocd.gdb"
+runner = "arm-none-eabi-gdb -q -x ../openocd.gdb"
+# runner = "gdb-multiarch -q"
+# runner = "gdb -q"
 rustflags = [
   "-C", "link-arg=-Tlink.x",
 ]
 
 [build]
 target = "thumbv7em-none-eabihf"
+
 ```
 
 With that in place, you can now use a simple `cargo run` command which will build
@@ -95,3 +141,12 @@ 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();
 ```
+
+## Fork the discovery book
+
+If you haven't already ready, it's probably a good idea to fork
+the [embedded discovery book](https://github.com/rust-embedded/discovery) so you
+can save your changes in your own branch of your fork. We suggest creating
+your own branch and leaving the `master` branch alone so the `master` branch
+of your fork can stay in sync with the upstream repo. Also, it allows you to
+more easily create PR's and improve this book, **thank you in advance**!

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

@@ -38,25 +38,19 @@ fn main() -> ! {
 ```
 
 Now build it:
-
 ``` console
-cargo build --target thumbv7em-none-eabihf
+cargo build
 ```
 
 > **NOTE** It's possible to forget to rebuild the program *before* starting a GDB session; this
 > omission can lead to very confusing debug sessions. To avoid this problem you can call just `cargo run`
 > instead of `cargo build`; `cargo run`. The `cargo run` command will build *and* start a debug
 > session ensuring you never forget to recompile your program.
 
-Now, we'll repeat the flashing procedure that we did in the previous section:
-
+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* :)
 ``` console
-cargo run --target thumbv7em-none-eabihf
-```
-
-Which results in something like:
-``` console
-$ cargo run --target thumbv7em-none-eabihf
+$ cargo run
     Finished dev [unoptimized + debuginfo] target(s) in 0.01s
      Running `arm-none-eabi-gdb -q ~/embedded-discovery/target/thumbv7em-none-eabihf/debug/led-roulette`
 Reading symbols from ~/embedded-discovery/target/thumbv7em-none-eabihf/debug/led-roulette...
@@ -93,7 +87,6 @@ led_roulette::__cortex_m_rt_main () at ~/embedded-discovery/src/05-led-roulette/
 
 OK. Let's step through the code. This time, we'll use the `next` command instead of `step`. The
 difference is that the `next` command will step *over* function calls instead of going inside them.
-
 ```
 (gdb) next
 11          let half_period = 500_u16;

src/06-hello-world/.cargo/config

@@ -1,8 +1,8 @@
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q -x openocd.gdb"
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-]
+#rustflags = [
+#  "-C", "link-arg=-Tlink.x",
+#]
 
 [build]
 target = "thumbv7em-none-eabihf"

src/07-registers/.cargo/config

@@ -1,8 +1,8 @@
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q -x openocd.gdb"
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-]
+#rustflags = [
+#  "-C", "link-arg=-Tlink.x",
+#]
 
 [build]
-target = "thumbv7em-none-eabihf"
+target = "thumbv7em-none-eabihf"

src/08-leds-again/.cargo/config

@@ -1,8 +1,8 @@
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q -x openocd.gdb"
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-]
+#rustflags = [
+#  "-C", "link-arg=-Tlink.x",
+#]
 
 [build]
-target = "thumbv7em-none-eabihf"
+target = "thumbv7em-none-eabihf"

src/09-clocks-and-timers/.cargo/config

@@ -1,8 +1,8 @@
 [target.thumbv7em-none-eabihf]
 runner = "arm-none-eabi-gdb -q -x openocd.gdb"
-rustflags = [
-  "-C", "link-arg=-Tlink.x",
-]
+#rustflags = [
+#  "-C", "link-arg=-Tlink.x",
+#]
 
 [build]
-target = "thumbv7em-none-eabihf"
+target = "thumbv7em-none-eabihf"