Merge #304

304: Update-03-setting-up-a-dev-env r=adamgreig a=winksaville

Update `*.md` files so that copy-to-clipboard button in code blocks
works so that commands can be copied and pasted into terminal windows.

Some reorganization of the text for clarity.

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

Author: bors[bot]

src/03-setup/README.md

@@ -38,7 +38,7 @@ should work but we have listed the version we have tested.
 
 - Rust 1.31 or a newer toolchain.
 
-- [`itmdump`] v0.3.1 (`cargo install itm`)
+- [`itmdump`] >=0.3.1 (`cargo install itm`). Tested versions: 0.3.1.
 
 - OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
 
@@ -84,37 +84,70 @@ rustc 1.31.0 (abe02cefd 2018-12-04)
 
 ### `itmdump`
 
+
 ``` console
-$ cargo install itm --vers 0.3.1
+cargo install itm
+```
 
+Verify the version is >=0.3.1
+```
 $ itmdump -V
 itmdump 0.3.1
 ```
 
 ### `cargo-binutils`
 
+Install `llvm-tools-preview`
+
 ``` console
-$ rustup component add llvm-tools-preview
+rustup component add llvm-tools-preview
+```
+
+Install `cargo-binutils`
+```
+cargo install cargo-binutils
+```
+
+#### Verify tools are installed
 
-$ cargo install cargo-binutils
+Run the following commands at your terminal
+``` console
+cargo new test-size
+```
+```
+cd test-size
+```
+```
+cargo run
+```
+```
+cargo size -- -version
+```
 
+The results should be something like:
+```
+~
 $ cargo new test-size
      Created binary (application) `test-size` package
 
+~
 $ cd test-size
 
+~/test-size (main)
 $ cargo run
-    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
-     Running `target\debug\test-size.exe`
+   Compiling test-size v0.1.0 (~/test-size)
+    Finished dev [unoptimized + debuginfo] target(s) in 0.26s
+     Running `target/debug/test-size`
 Hello, world!
 
+~/test-size (main)
 $ cargo size -- -version
-    Finished dev [unoptimized + debuginfo] target(s) in 0.50s
+    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
 LLVM (http://llvm.org/):
-  LLVM version 11.0.0-rust-1.49.0-stable
+  LLVM version 11.0.0-rust-1.50.0-stable
   Optimized build.
-  Default target: x86_64-pc-windows-msvc
-  Host CPU: skylake
+  Default target: x86_64-unknown-linux-gnu
+  Host CPU: znver2
 ```
 
 ### OS specific instructions

src/03-setup/linux.md

@@ -18,7 +18,7 @@ Here are the installation commands for a few Linux distributions.
 <!-- OpenOCD 0.10.0 -->
 
 ``` console
-$ sudo apt-get install \
+sudo apt-get install \
   gdb-multiarch \
   minicom \
   openocd
@@ -34,7 +34,7 @@ $ sudo apt-get install \
 <!-- OpenOCD 0.7.0 -->
 
 ``` console
-$ sudo apt-get install \
+sudo apt-get install \
   gdb-arm-none-eabi \
   minicom \
   openocd
@@ -46,7 +46,7 @@ $ sudo apt-get install \
 > Cortex-M programs
 
 ``` console
-$ sudo dnf install \
+sudo dnf install \
   arm-none-eabi-gdb \
   minicom \
   openocd
@@ -58,7 +58,7 @@ $ sudo dnf install \
 > Cortex-M programs
 
 ``` console
-$ sudo pacman -S \
+sudo pacman -S \
   arm-none-eabi-gdb \
   minicom \
   openocd
@@ -75,39 +75,41 @@ download the "Linux 64-bit" file and put its `bin` directory on your path.
 Here's one way to do it:
 
 ``` console
-$ mkdir -p ~/local && cd ~/local
-$ tar xjf /path/to/downloaded/file/gcc-arm-none-eabi-7-2017-q4-major-linux.tar.bz2.tbz
+mkdir -p ~/local && cd ~/local
+```
+``` console
+tar xjf /path/to/downloaded/file/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux.tar.bz2
 ```
 
 Then, use your editor of choice to append to your `PATH` in the appropriate
 shell init file (e.g. `~/.zshrc` or `~/.bashrc`):
 
 ```
-PATH=$PATH:$HOME/local/gcc-arm-none-eabi-7-2017-q4-major/bin
+PATH=$PATH:$HOME/local/gcc-arm-none-eabi-10-2020-q4-major-x86_64-linux/bin
 ```
 
 ## Optional packages
 
 ### Ubuntu / Debian
 
 ``` console
-$ sudo apt-get install \
+sudo apt-get install \
   bluez \
   rfkill
 ```
 
 ### Fedora
 
 ``` console
-$ sudo dnf install \
+sudo dnf install \
   bluez \
   rfkill
 ```
 
 ### Arch Linux
 
 ``` console
-$ sudo pacman -S \
+sudo pacman -S \
   bluez \
   bluez-utils \
   rfkill
@@ -118,35 +120,49 @@ $ sudo pacman -S \
 These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e.
 `sudo`.
 
-Create these two files in `/etc/udev/rules.d` with the contents shown below.
+Create `99-openocd.rules` in `/etc/udev/rules.d` using the `idVendor` and `idProduct`
+from the `lsusb` output.
 
+For example, connect the STM32F3DISCOVERY to your computer using a USB cable.
+Be sure to connect the cable to the "USB ST-LINK" port, the USB port in the
+center of the edge of the board.
+
+Execute `lsusb`:
 ``` console
-$ cat /etc/udev/rules.d/99-ftdi.rules
+lsusb | grep ST-LINK
+```
+It should result in something like:
 ```
+$ lsusb | grep ST-LINK
+Bus 003 Device 003: ID 0483:374b STMicroelectronics ST-LINK/V2.1
+```
+So the `idProduct` is `0483` and `idVendor` is `374b`.
 
+### Create `/etc/udev/rules.d/99-openocd.rules`:
+``` console
+sudo vi /etc/udev/rules.d/99-openocd.rules
+```
+With the contents:
 ``` text
-# FT232 - USB <-> Serial Converter
-ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666"
+# STM32F3DISCOVERY - ST-LINK/V2.1
+ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
 ```
+#### For older devices with OPTIONAL USB <-> FT232 based Serial Module
 
-If you have a different USB <-> Serial converter, get its vendor and product ids from `lsusb` output.
-
+Create `/etc/udev/rules.d/99-ftdi.rules`:
 ``` console
-$ cat /etc/udev/rules.d/99-openocd.rules
+sudo vi /etc/udev/rules.d/99-openocd.rules
 ```
-
+With the contents:
 ``` text
-# STM32F3DISCOVERY rev A/B - ST-LINK/V2
-ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"
-
-# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1
-ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
+# FT232 - USB <-> Serial Converter
+ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", MODE:="0666"
 ```
 
-Then reload the udev rules with:
+### Reload the udev rules with:
 
 ``` console
-$ sudo udevadm control --reload-rules
+sudo udevadm control --reload-rules
 ```
 
 If you had any board plugged to your computer, unplug them and then plug them in again.

src/03-setup/macos.md

@@ -4,13 +4,17 @@ All the tools can be install using [Homebrew]:
 
 [Homebrew]: http://brew.sh/
 
+Install ArmMbed
 ``` console
-$ # Arm GCC toolchain
-$ brew tap ArmMbed/homebrew-formulae
-$ brew install arm-none-eabi-gcc
-
-$ # Minicom and OpenOCD
-$ brew install minicom openocd
+brew tap ArmMbed/homebrew-formulae
+```
+Install the ARM GCC toolchain
+``` console
+brew install arm-none-eabi-gcc
+```
+Install minicom and OpenOCD
+``` console
+brew install minicom openocd
 ```
 
 That's all! Go to the [next section].

src/03-setup/verify.md

@@ -6,24 +6,27 @@ Let's verify that all the tools were installed correctly.
 
 ### Verify permissions
 
-Connect the F3 to your computer using an USB cable. Be sure to connect the cable to the "USB ST-LINK"
+Connect the STM32F3DISCOVERY to your computer using an USB cable. Be sure to connect the cable to the "USB ST-LINK"
 port, the USB port in the center of the edge of the board.
 
-The F3 should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got
+The STM32F3DISCOVERY should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got
 enumerated:
 
+``` console
+lsusb | grep -i stm
+```
+This should result in:
 ``` console
 $ lsusb | grep -i stm
 Bus 003 Device 004: ID 0483:374b STMicroelectronics ST-LINK/V2.1
 $ # ^^^        ^^^
 ```
 
-In my case, the F3 got connected to the bus #3 and got enumerated as the device #4. This means the
-file `/dev/bus/usb/003/004` *is* the F3. Let's check its permissions:
-
+In my case, the STM32F3DISCOVERY got connected to the bus #3 and got enumerated as the device #4. This means the
+file `/dev/bus/usb/003/004` *is* the STM32F3DISCOVERY. Let's check its permissions:
 ``` console
-$ ls -l /dev/bus/usb/003/004
-crw-rw-rw- 1 root root 189, 20 Sep 13 00:00 /dev/bus/usb/003/004
+$ ls -la /dev/bus/usb/003/004
+crw-rw-rw-+ 1 root root 189, 259 Feb 28 13:32 /dev/bus/usb/003/00
 ```
 
 The permissions should be `crw-rw-rw-`. If it's not ... then check your [udev
@@ -32,12 +35,12 @@ rules] and try re-loading them with:
 [udev rules]: linux.md#udev-rules
 
 ``` console
-$ sudo udevadm control --reload-rules
+sudo udevadm control --reload-rules
 ```
 
-Now let's repeat the procedure for the Serial module.
+#### For older devices with OPTIONAL USB <-> FT232 based Serial Module
 
-Unplug the F3 and plug the Serial module. Now, figure out what's its associated file:
+Unplug the STM32F3DISCOVERY and plug the Serial module. Now, figure out what's its associated file:
 
 ``` console
 $ lsusb | grep -i ft232
@@ -53,36 +56,51 @@ crw-rw-rw- 1 root root 189, 21 Sep 13 00:00 /dev/bus/usb/003/005
 
 As before, the permissions should be `crw-rw-rw-`.
 
-## All
+## Verify OpenOCD connection
 
-### First OpenOCD connection
-
-First, connect the F3 to your computer using an USB cable. Connect the cable to the USB port in the
+Connect the STM32F3DISCOVERY using the USB cable to the USB port in the
 center of edge of the board, the one that's labeled "USB ST-LINK".
 
 Two *red* LEDs should turn on right after connecting the USB cable to the board.
 
-Next, run this command:
+> **IMPORTANT** There is more than one hardware revision of the STM32F3DISCOVERY board. For older
+> revisions, you'll need to change the "interface" argument to `-f interface/stlink-v2.cfg` (note:
+> no `-1` at the end). Alternatively, older revisions can use `-f board/stm32f3discovery.cfg`
+> instead of `-f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg`.
+
+### *Nix
+
+> **FYI:** The `interface` directory is typically located in `/usr/share/openocd/scripts/`,
+> which is the default location OpenOCD expects these files. If you've installed them
+> somewhere else use the `-s /path/to/scripts/` option to specify your install directory.
 
 ``` console
-$ # *nix
-$ openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
+openocd -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
+```
 
-$ # Windows
-$ # NOTE cygwin users have reported problems with the -s flag. If you run into
-$ # that you can call openocd from the `C:\OpenOCD\share\scripts` directory
-$ openocd -s C:\OpenOCD\share\scripts -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
+### Windows
+
+Below the references to `C:\OpenOCD` is the directory where OpenOCD is installed.
+
+``` console
+openocd -s C:\OpenOCD\share\scripts -f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg
 ```
 
-> **NOTE** Windows users: `C:\OpenOCD` is the directory where you installed OpenOCD to.
+> **NOTE** cygwin users have reported problems with the -s flag. If you run into
+> that problem you can add `C:\OpenOCD\share\scripts\` directory to the parameters.
 
-> **IMPORTANT** There is more than one hardware revision of the STM32F3DISCOVERY board. For older
-> revisions, you'll need to change the "interface" argument to `-f interface/stlink-v2.cfg` (note:
-> no `-1` at the end). Alternatively, older revisions can use `-f board/stm32f3discovery.cfg`
-> instead of `-f interface/stlink-v2-1.cfg -f target/stm32f3x.cfg`.
+cygwin users:
+``` console
+openocd -f C:\OpenOCD\share\scripts\interface\stlink-v2-1.cfg -f C:\OpenOCD\share\scripts\target\stm32f3x.cfg
+```
 
-You should see output like this:
+### All
 
+OpenOCD is a service which forwards debug information from the ITM channel
+to a file, `itm.txt`, as such it runs forever and does **not** return to the
+terminal prompt.
+
+The initial output of OpenOCD is something like:
 ``` console
 Open On-Chip Debugger 0.10.0
 Licensed under GNU GPL v2
@@ -106,9 +124,7 @@ Info : stm32f3x.cpu: hardware has 6 breakpoints, 4 watchpoints
 
 [general troubleshooting]: ../appendix/1-general-troubleshooting/index.html
 
-`openocd` will block the terminal. That's fine.
-
 Also, one of the red LEDs, the one closest to the USB port, should start oscillating between red
 light and green light.
 
-That's it! It works. You can now close/kill `openocd`.
+That's it! It works. You can now use `Ctrl-c` to stop OpenOCD or close/kill the terminal.