edited ch 3

rust-embedded · Jul 10, 2024 · 4eb4591 · 4eb4591
1 parent a2ab726
commit 4eb4591
Show file tree

Hide file tree

Showing 5 changed files with 110 additions and 181 deletions.
diff --git a/mdbook/src/03-setup/README.md b/mdbook/src/03-setup/README.md
@@ -6,35 +6,32 @@ different from your computer's and we'll have to run and debug programs on a "re
 ## Documentation
 
 Tooling is not everything though. Without documentation, it is pretty much impossible to work with
-microcontrollers.
-
-We'll be referring to all these documents throughout this book:
-
-- [LSM303AGR]
-
-[LSM303AGR]: https://www.st.com/resource/en/datasheet/lsm303agr.pdf
+microcontrollers. The official MB2 technical documentation is at <https://tech.microbit.org>. We
+will reference other technical documentation throughout the book.
 
 ## Tools
 
 We'll use all the tools listed below. Where a minimum version is not specified, any recent version
 should work but we have listed the version we have tested.
 
-- Rust 1.57.0 or a newer toolchain.
+- Rust 1.79.0 or a newer toolchain.
 
-- `gdb-multiarch`. Tested version: 10.2. Other versions will most likely work as well though
-  If your distribution/platform does not have `gdb-multiarch` available `arm-none-eabi-gdb`
-  will do the trick as well. Furthermore, some normal `gdb` binaries are built with multiarch
-  capabilities as well, you can find further information about this in the sub chapters.
+- `gdb-multiarch`. This is a debugging tool. The oldest tested version is10.2, but other versions
+  will most likely work as well.  If your distribution/platform does not have `gdb-multiarch`
+  available `arm-none-eabi-gdb` will do the trick as well. Furthermore, some normal `gdb` binaries
+  are built with multiarch capabilities as well: you can find further information about this in the
+  debugging chapter of this book.
 
-- [`cargo-binutils`]. Version 0.3.3 or newer.
+- [`cargo-binutils`]. Version 0.3.6 or newer.
 
-[`cargo-binutils`]: https://github.com/rust-embedded/cargo-binutils
+  [`cargo-binutils`]: https://github.com/rust-embedded/cargo-binutils
 
-- [`cargo-embed`]. Version 0.24.0 or newer.
+- [`probe-rs-tools`]. Version 0.24.0.
 
-[`cargo-embed`]: https://probe.rs/docs/tools/cargo-embed/
+  [`probe-rs-tools`]: https://probe.rs/docs/overview/about-probe-rs/
 
-- `minicom` on Linux and macOS. Tested version: 2.7.1. Other versions will most likely work as well though
+- `minicom` on Linux and macOS. Tested version: 2.7.1. Other versions will most likely work as well
+  though.
 
 - `PuTTY` on Windows.
 
@@ -44,46 +41,53 @@ Next, follow OS-agnostic installation instructions for a few of the tools:
 
 Install rustup by following the instructions at [https://rustup.rs](https://rustup.rs).
 
-If you already have rustup installed double check that you are on the stable
-channel and your stable toolchain is up-to-date. `rustc -V` should return a date
-newer than the one shown below:
+If you already have rustup installed, double check that you are on the stable channel and your
+stable toolchain is up-to-date. `rustc -V` should return a date and version no older than the one
+shown below:
 
 ``` console
 $ rustc -V
-rustc 1.53.0 (53cb7b09b 2021-06-17)
+rustc 1.79.0 (129f3b996 2024-06-10)
 ```
 
 ### `cargo-binutils`
 
 ``` console
 $ rustup component add llvm-tools
-
 $ cargo install cargo-binutils --vers 0.3.3
-
 $ cargo size --version
-cargo-size 0.3.3
+cargo-size 0.3.6
 ```
 
-### `cargo-embed`
+### `probe-rs-tools`
 
-In order to install cargo-embed, first install its [prerequisites](https://probe.rs/docs/getting-started/installation/) (note: these instructions are part of the more general [`probe-rs`](https://probe.rs/) embedded debugging toolkit). Then install it with cargo:
+In order to install `probe-rs-tools`, first install its
+[prerequisites](https://probe.rs/docs/getting-started/installation/) (note: these instructions are
+part of the more general [`probe-rs`](https://probe.rs/) embedded debugging toolkit). Then install
+it with Cargo.
 
 ```console
 $ cargo install probe-rs-tools --vers 0.24.0
+```
+
+This will install several useful tools, including `probe-rs` and `cargo-embed` (which is normally
+run as a Cargo command).
 
+```
 $ cargo embed --version
 cargo-embed 0.24.0 (git commit: crates.io)
 ```
 
 ### This repository
 
-Since this book also contains some small Rust code bases used in various chapters
-you will also have to download its source code. You can do this in one of the following ways:
+This book also contains some small Rust codebases used in various chapters: the easiest way to use
+these is to download the book's source code. You can do this in one of the following ways:
+
+- Visit the [repository](https://github.com/rust-embedded/discovery-mb2/), click the green "Code"
+  button and then the "Download Zip" one.
 
-* Visit the [repository](https://github.com/rust-embedded/discovery/), click the green "Code" button and then the
-   "Download Zip" one
-* Clone it using git (if you know git you presumably already have it installed) from the same repository as linked in
-   the zip approach
+- Clone it using `git` (if you know `git` you presumably already have it installed) from the same
+  repository as linked in the Zip approach.
 
 ### OS specific instructions
 

diff --git a/mdbook/src/03-setup/linux.md b/mdbook/src/03-setup/linux.md
@@ -4,53 +4,46 @@ Here are the installation commands for a few Linux distributions.
 
 ## Ubuntu 20.04 or newer / Debian 10 or newer
 
-> **NOTE** `gdb-multiarch` is the GDB command you'll use to debug your ARM
-> Cortex-M programs
+> **NOTE** `gdb-multiarch` is the GDB command you'll use to debug your ARM Cortex-M programs.
 ``` console
-$ sudo apt-get install \
-  gdb-multiarch \
-  minicom
+$ sudo apt install gdb-multiarch minicom libunwind-dev
 ```
 
 ## Fedora 32 or newer
+
 > **NOTE** `gdb` is the GDB command you'll use to debug your ARM
-> Cortex-M programs
+> Cortex-M programs.
 ``` console
-$ sudo dnf install \
-  gdb \
-  minicom
+$ sudo dnf install gdb minicom libunwind-devel
 ```
 
 ## Arch Linux
 
 > **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM
-> Cortex-M programs
+> Cortex-M programs.
 ``` console
-$ sudo pacman -S \
-  arm-none-eabi-gdb \
-  minicom
+$ sudo pacman -S arm-none-eabi-gdb minicom libunwind-dev
 ```
 
 ## Other distros
 
-> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM
-> Cortex-M programs
+> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM Cortex-M programs.
 
 For distros that don't have packages for [ARM's pre-built
-toolchain](https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads),
-download the "Linux 64-bit" file and put its `bin` directory on your path.
-Here's one way to do it:
+toolchain](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads), 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-9-2020-q2-update-x86_64-linux.tar.bz2
+$ mkdir -p ~/local
+$ cd ~/local
+$ tar xjf /path/to/downloaded/XXX.tar.bz2
 ```
 
-Then, use your editor of choice to append to your `PATH` in the appropriate
-shell init file (e.g. `~/.zshrc` or `~/.bashrc`):
+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-9-2020-q2-update/bin
+PATH=$PATH:$HOME/local/XXX/bin
 ```
 
 ## udev rules
@@ -76,9 +69,57 @@ Then reload the udev rules with:
 $ sudo udevadm control --reload
 ```
 
-If you had any board plugged to your computer, unplug them and then plug them in again, or run the following command.
+If you had any board plugged to your computer, unplug them and then plug them in again, or run the
+following command.
+
+``` console
+$ sudo udevadm trigger
+```
+
+## Verify permissions
+
+Connect the micro:bit to your computer using a USB cable.
+
+The micro:bit should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got
+enumerated:
 
 ``` console
+$ lsusb | grep -i "NXP ARM mbed"
+Bus 001 Device 065: ID 0d28:0204 NXP ARM mbed
+$ # ^^^        ^^^
+```
+
+In my case, the micro:bit got connected to the bus #1 and got enumerated as the device #65. This means the
+file `/dev/bus/usb/001/065` *is* the micro:bit. Let's check the file permissions:
+
+``` console
+$ ls -l /dev/bus/usb/001/065
+crw-rw-r--+ 1 nobody nobody 189, 64 Sep  5 14:27 /dev/bus/usb/001/065
+```
+
+The permissions should be `crw-rw-r--+`, note the `+` at the end, then see your access rights by running the following command.
+
+``` console
+$ getfacl /dev/bus/usb/001/065
+getfacl: Removing leadin '/' from absolute path names
+# file: dev/bus/usb/001/065
+# owner: nobody
+# group: nobody
+user::rw-
+user:<YOUR-USER-NAME>:rw-
+group::rw-
+mask::rw-
+other::r-
+```
+
+You should see your username in the list above with the
+`rw-` permissions, if not ... then check your [udev rules]
+and try re-loading them with:
+
+[udev rules]: linux.md#udev-rules
+
+``` console
+$ sudo udevadm control --reload
 $ sudo udevadm trigger
 ```
 

diff --git a/mdbook/src/03-setup/verify.md b/mdbook/src/03-setup/verify.md
@@ -2,65 +2,17 @@
 
 Let's verify that all the tools were installed correctly.
 
-## Linux only
-
-### Verify permissions
-
-Connect the micro:bit to your computer using a USB cable.
-
-The micro:bit should now appear as a USB device (file) in `/dev/bus/usb`. Let's find out how it got
-enumerated:
-
-``` console
-$ lsusb | grep -i "NXP ARM mbed"
-Bus 001 Device 065: ID 0d28:0204 NXP ARM mbed
-$ # ^^^        ^^^
-```
-
-In my case, the micro:bit got connected to the bus #1 and got enumerated as the device #65. This means the
-file `/dev/bus/usb/001/065` *is* the micro:bit. Let's check the file permissions:
-
-``` console
-$ ls -l /dev/bus/usb/001/065
-crw-rw-r--+ 1 nobody nobody 189, 64 Sep  5 14:27 /dev/bus/usb/001/065
-```
-
-The permissions should be `crw-rw-r--+`, note the `+` at the end, then see your access rights by running the following command.
-
-``` console
-$ getfacl /dev/bus/usb/001/065
-getfacl: Removing leadin '/' from absolute path names
-# file: dev/bus/usb/001/065
-# owner: nobody
-# group: nobody
-user::rw-
-user:<YOUR-USER-NAME>:rw-
-group::rw-
-mask::rw-
-other::r-
-```
-
-You should see your username in the list above with the `rw-` permissions, if not ... then check your [udev
-rules] and try re-loading them with:
-
-[udev rules]: linux.md#udev-rules
-
-``` console
-$ sudo udevadm control --reload
-$ sudo udevadm trigger
-```
-
-# All
-
 ## Verifying cargo-embed
+
 First, connect the micro:bit to your Computer using a USB cable.
 
-At least an orange LED right next to the USB port of the micro:bit should light up.
-Furthermore, if you have never flashed another program on to your micro:bit, the default
-program the micro:bit ships with should start blinking the red LEDs on its back, you
-can ignore them.
+At least an orange LED right next to the USB port of the micro:bit should light up.  Furthermore, if
+you have never flashed another program on to your micro:bit, the default program the micro:bit ships
+with should start blinking the red LEDs on its back: you can ignore them, or you can play with the
+demo app.
 
-Now let's see if probe-rs, and by extensions cargo-embed can see your micro:bit, you can do this by running the following command.
+Now let's see if probe-rs, and by extensions cargo-embed can see your micro:bit. You can do this by
+running the following command:
 
 ``` console
 $ probe-rs list
@@ -98,13 +50,11 @@ Debug Port: DPv1, DP Designer: ARM Ltd
 
 Debugging RISC-V targets over SWD is not supported. For these targets, JTAG is the only supported protocol. RISC-V specific information cannot be printed.
 Debugging Xtensa targets over SWD is not supported. For these targets, JTAG is the only supported protocol. Xtensa specific information cannot be printed.
-
 ```
 
-Next run one of these commands:
+Next, make sure you are in `src/03-setup` of this book's source code. Then run these commands:
 
 ```
-$ # make sure you are in src/03-setup of the books source code
 $ rustup target add thumbv7em-none-eabihf
 $ cargo embed --target thumbv7em-none-eabihf
 ```

diff --git a/mdbook/src/03-setup/windows.md b/mdbook/src/03-setup/windows.md
@@ -12,7 +12,7 @@ $ arm-none-eabi-gcc -v
 gcc version 5.4.1 20160919 (release) (..)
 ```
 
-[gcc]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads
+[gcc]: https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads
 
 ## PuTTY