Merge branch 'master' into patch-10

README.md

@@ -1,10 +1,10 @@
-# [Work in Progress] - The Embedded Rust Book
+# The Embedded Rust Book
 
 > Documentation on how to use the Rust Programming Language to develop firmware for bare metal (microcontroller) devices
 
 This project is developed and maintained by the [Resources team][team].
 
-See [the issue tracker] for more details. This is a very early work in progress.
+See [the issue tracker] for more details. This book is a living document, and is updated continuously.
 
 [the issue tracker]: https://github.com/rust-embedded/book/issues
 
@@ -43,4 +43,4 @@ Conduct][CoC], the maintainer of this crate, the [Resources team][team], promise
 to intervene to uphold that code of conduct.
 
 [CoC]: CODE_OF_CONDUCT.md
-[team]: https://github.com/rust-embedded/wg#the-cortex-m-team
+[team]: https://github.com/rust-embedded/wg#the-resources-team

ci/script.sh

@@ -2,6 +2,7 @@ set -euxo pipefail
 
 main() {
     mdbook build
+    mdbook test
 
     # FIXME(rust-lang-nursery/mdbook#789) remove `--ignore-url` when that bug is fixed
     linkchecker --ignore-url "print.html" book

src/SUMMARY.md

@@ -10,14 +10,14 @@ more information and coordination
 -->
 
 - [Introduction](./intro/index.md)
+    - [Hardware](./intro/hardware.md)
     - [`no_std`](./intro/no-std.md)
     - [Tooling](./intro/tooling.md)
     - [Installation](./intro/install.md)
         - [Linux](./intro/install/linux.md)
         - [MacOS](./intro/install/macos.md)
         - [Windows](./intro/install/windows.md)
         - [Verify Installation](./intro/install/verify.md)
-    - [Hardware](./intro/hardware.md)
 - [Getting started](./start/index.md)
   - [QEMU](./start/qemu.md)
   - [Hardware](./start/hardware.md)

src/c-tips/index.md

@@ -79,7 +79,7 @@ for example:
 const fn array_size() -> usize {
     #[cfg(feature="use_more_ram")]
     { 1024 }
-    #[cfg(not(feature="use_more_ram")]
+    #[cfg(not(feature="use_more_ram"))]
     { 128 }
 }
 
@@ -102,7 +102,7 @@ item, or pattern. Procedural macros are more complex but permit extremely
 powerful additions to the Rust language: they can transform arbitrary Rust
 syntax into new Rust syntax.
 
-[macro system]: https://doc.rust-lang.org/book/second-edition/appendix-04-macros.html
+[macro system]: https://doc.rust-lang.org/book/ch19-06-macros.html
 
 In general, where you might have used a C preprocessor macro, you probably want
 to see if a macro-by-example can do the job instead. They can be defined in
@@ -180,7 +180,7 @@ happily index outside the array.
 
 Instead, use iterators:
 
-```rust
+```rust,ignore
 let arr = [0u16; 16];
 for element in arr.iter() {
     process(*element);
@@ -194,7 +194,7 @@ data processing code.
 
 See the [Iterators in the Book] and [Iterator documentation] for more details.
 
-[Iterators in the Book]: https://doc.rust-lang.org/book/second-edition/ch13-02-iterators.html
+[Iterators in the Book]: https://doc.rust-lang.org/book/ch13-02-iterators.html
 [Iterator documentation]: https://doc.rust-lang.org/core/iter/trait.Iterator.html
 
 ## References vs Pointers
@@ -259,7 +259,7 @@ void driver() {
 
 The equivalent in Rust would use volatile methods on each access:
 
-```rust
+```rust,ignore
 static mut SIGNALLED: bool = false;
 
 #[interrupt]

src/collections/index.md

@@ -118,7 +118,7 @@ fn on_oom(_layout: Layout) -> ! {
 
 Once all that is in place, the user can finally use the collections in `alloc`.
 
-``` rust
+```rust,ignore
 #[entry]
 fn main() -> ! {
     let mut xs = Vec::new();
@@ -140,7 +140,7 @@ as they are exact same implementation.
 `heapless` requires no setup as its collections don't depend on a global memory
 allocator. Just `use` its collections and proceed to instantiate them:
 
-``` rust
+```rust,ignore
 extern crate heapless; // v0.4.x
 
 use heapless::Vec;

src/concurrency/index.md

@@ -22,7 +22,7 @@ are no interrupts at all. Sometimes this is perfectly suited to the problem
 at hand! Typically your loop will read some inputs, perform some processing,
 and write some outputs.
 
-```rust
+```rust,ignore
 #[entry]
 fn main() {
     let peripherals = setup_peripherals();
@@ -58,7 +58,7 @@ For an example of how this behaviour can cause subtle errors in your code,
 consider an embedded program which counts rising edges of some input signal
 in each one-second period (a frequency counter):
 
-```rust
+```rust,ignore
 static mut COUNTER: u32 = 0;
 
 #[entry]
@@ -99,7 +99,7 @@ sections_, a context where interrupts are disabled. By wrapping the access to
 `COUNTER` in `main` in a critical section, we can be sure the timer interrupt
 will not fire until we're finished incrementing `COUNTER`:
 
-```rust
+```rust,ignore
 static mut COUNTER: u32 = 0;
 
 #[entry]
@@ -160,7 +160,7 @@ of the time, but if it was interrupted it will automatically retry the entire
 increment operation. These atomic operations are safe even across multiple
 cores.
 
-```rust
+```rust,ignore
 use core::sync::atomic::{AtomicUsize, Ordering};
 
 static COUNTER: AtomicUsize = AtomicUsize::new(0);
@@ -215,7 +215,7 @@ We can abstract our counter into a safe interface which can be safely used
 anywhere else in our code. For this example we'll use the critical-section
 counter, but you could do something very similar with atomics.
 
-```rust
+```rust,ignore
 use core::cell::UnsafeCell;
 use cortex_m::interrupt;
 
@@ -340,7 +340,7 @@ the lock/unlock state of the mutex.
 This is in fact done for us in the `cortex_m` crate! We could have written
 our counter using it:
 
-```rust
+```rust,ignore
 use core::cell::Cell;
 use cortex_m::interrupt::Mutex;
 
@@ -410,7 +410,7 @@ the shared variable after it has been initialised in the main code. To do
 this we can use the `Option` type, initialised to `None` and later set to
 the instance of the peripheral.
 
-```rust
+```rust,ignore
 use core::cell::RefCell;
 use cortex_m::interrupt::{self, Mutex};
 use stm32f4::stm32f405;

src/interoperability/c-with-rust.md

@@ -120,7 +120,7 @@ For projects with limited dependencies or complexity, or for projects where it i
 
 In the simplest case of compiling a single C file as a dependency to a static library, an example `build.rs` script using the [`cc` crate] would look like this:
 
-```rust
+```rust,ignore
 extern crate cc;
 
 fn main() {

src/intro/hardware.md

@@ -8,37 +8,32 @@ Let's get familiar with the hardware we'll be working with.
 <img title="F3" src="../assets/f3.jpg">
 </p>
 
-We'll refer to this board as "F3" throughout this book.
-
 What does this board contain?
 
-- A STM32F303VCT6 microcontroller. This microcontroller has
+- A [STM32F303VCT6](https://www.st.com/en/microcontrollers/stm32f303vc.html) microcontroller. This microcontroller has
   - A single-core ARM Cortex-M4F processor with hardware support for single-precision floating point
     operations and a maximum clock frequency of 72 MHz.
 
   - 256 KiB of "Flash" memory. (1 KiB = 10**24** bytes)
 
   - 48 KiB of RAM.
 
-  - many "peripherals": timers, GPIO, I2C, SPI, USART, etc.
-
-  - lots of "pins" that are exposed in the two lateral "headers".
+  - A variety of integrated peripherals such as timers, I2C, SPI and USART.
 
-  - **IMPORTANT** This microcontroller operates at (around) 3.3V.
+  - General purpose Input Output (GPIO) and other types of pins accessible through the two rows of headers along side the board.
+
+  - A USB interface accessible through the USB port labeled "USB USER".
 
-- An [accelerometer] and a [magnetometer][] (in a single package).
+- An [accelerometer](https://en.wikipedia.org/wiki/Accelerometer) as part of the [LSM303DLHC](https://www.st.com/en/mems-and-sensors/lsm303dlhc.html) chip.
 
-[accelerometer]: https://en.wikipedia.org/wiki/Accelerometer
-[magnetometer]: https://en.wikipedia.org/wiki/Magnetometer
+- A [magnetometer](https://en.wikipedia.org/wiki/Magnetometer) as part of the [LSM303DLHC](https://www.st.com/en/mems-and-sensors/lsm303dlhc.html) chip.
 
-- A [gyroscope].
+- A [gyroscope](https://en.wikipedia.org/wiki/Gyroscope) as part of the [L3GD20](https://www.pololu.com/file/0J563/L3GD20.pdf) chip.
 
-[gyroscope]: https://en.wikipedia.org/wiki/Gyroscope
+- 8 user LEDs arranged in the shape of a compass.
 
-- 8 user LEDs arranged in the shape of a compass
+- A second microcontroller: a [STM32F103](https://www.st.com/en/microcontrollers/stm32f103cb.html). This microcontroller is actually part of an on-board programmer / debugger and is connected to the USB port named "USB ST-LINK".
 
-- A second microcontroller: a STM32F103CBT. This microcontroller is actually part of an on-board
-  programmer and debugger named ST-LINK and is connected to the USB port named "USB ST-LINK".
+For a more detailed list of features and further specifications of the board take a look at the [STMicroelectronics](https://www.st.com/en/evaluation-tools/stm32f3discovery.html) website.
 
-- There's a second USB port, labeled "USB USER" that is connected to the main microcontroller, the
-  STM32F303VCT6, and can be used in applications.
+A word of caution: be careful if you want to apply external signals to the board. The microcontroller STM32F303VCT6 pins take a nominal voltage of 3.3 volts. For further information consult the [6.2 Absolute maximum ratings section in the manual](https://www.st.com/resource/en/datasheet/stm32f303vc.pdf)

src/intro/index.md

@@ -4,8 +4,8 @@ Welcome to The Embedded Rust Book: An introductory book about using the Rust
 Programming Language on "Bare Metal" embedded systems, such as Microcontrollers.
 
 ## Who Embedded Rust is For
-Embedded Rust is for everyone who wants to do embedded programming backed by the higher-level concepts and safety guarantees the Rust language provides.
-(See also [Who Rust Is For](https://doc.rust-lang.org/book/2018-edition/ch00-00-introduction.html))
+Embedded Rust is for everyone who wants to do embedded programming while taking advantage of the higher-level concepts and safety guarantees the Rust language provides.
+(See also [Who Rust Is For](https://doc.rust-lang.org/book/ch00-00-introduction.html))
 
 ## Scope
 
@@ -23,16 +23,16 @@ The goals of this book are:
 
 This book tries to be as general as possible but to make things easier for both
 the readers and the writers it uses the ARM Cortex-M architecture in all its
-examples. However, the book assumes that the reader is not familiar with this
+examples. However, the book doesn't assume that the reader is familiar with this
 particular architecture and explains details particular to this architecture
 where required.
 
 ## Who This Book is For
-This book caters towards people with either some embedded background or some Rust background, however we assume
+This book caters towards people with either some embedded background or some Rust background, however we believe
 everybody curious about embedded Rust programming can get something out of this book. For those without any prior knowledge
 we suggest you read the "Assumptions and Prerequisites" section and catch up on missing knowledge to get more out of the book
 and improve your reading experience. You can check out the "Other Resources" section to find resources on topics
-you want to catch up on.
+you might want to catch up on.
 
 ### Assumptions and Prerequisites
 
@@ -41,7 +41,7 @@ you want to catch up on.
   be familiar with the idioms of the [2018 edition] as this book targets
   Rust 2018.
 
-[2018 edition]: https://rust-lang-nursery.github.io/edition-guide/
+[2018 edition]: https://doc.rust-lang.org/edition-guide/
 
 * You are comfortable developing and debugging embedded systems in another
   language such as C, C++, or Ada, and are familiar with concepts such as:
@@ -55,7 +55,7 @@ If you are unfamiliar with anything mentioned above or if you want more informat
 
 | Topic        | Resource | Description |
 |--------------|----------|-------------|
-| Rust         | [Rust Book 2018 Edition](https://doc.rust-lang.org/book/2018-edition/index.html) | If you are not yet comfortable with Rust, we highly suggest reading the this book. |
+| Rust         | [Rust Book](https://doc.rust-lang.org/book/) | If you are not yet comfortable with Rust, we highly suggest reading this book. |
 | Rust, Embedded | [Embedded Rust Bookshelf](https://docs.rust-embedded.org) | Here you can find several other resources provided by Rust's Embedded Working Group. |
 | Rust, Embedded | [Embedonomicon](https://docs.rust-embedded.org/embedonomicon/) | The nitty gritty details when doing embedded programming in Rust. |
 | Rust, Embedded | [embedded FAQ](https://docs.rust-embedded.org/faq.html) | Frequently asked questions about Rust in an embedded context. |
@@ -72,7 +72,7 @@ not dig into details on a topic, revisiting the topic in a later chapter.
 This book will be using the [STM32F3DISCOVERY] development board from
 STMicroelectronics for the majority of the examples contained within. This board
 is based on the ARM Cortex-M architecture, and while basic functionality is
-common across most CPUs based on this architecture, peripherals and other
+the same across most CPUs based on this architecture, peripherals and other
 implementation details of Microcontrollers are different between different
 vendors, and often even different between Microcontroller families from the same
 vendor.

src/intro/install.md

@@ -16,25 +16,25 @@ rustc 1.31.1 (b6c32da9b 2018-12-18)
 
 For bandwidth and disk usage concerns the default installation only supports
 native compilation. To add cross compilation support for the ARM Cortex-M
-architecture choose one of the following compilation targets. Use the last one
-for the STM32F3DISCOVERY board and follow along with the book.
+architectures choose one of the following compilation targets. For the STM32F3DISCOVERY
+board used for the examples in this book, use the final `thumbv7em-none-eabihf` target.
 
-Cortex M0 M0+
+Cortex-M0, M0+, and M1 (ARMv6-M architecture):
 ``` console
 $ rustup target add thumbv6m-none-eabi
 ```
 
-Cortex M3
+Cortex-M3 (ARMv7-M architecture):
 ``` console
 $ rustup target add thumbv7m-none-eabi
 ```
 
-Cortex M4 M7 without FPU
+Cortex-M4 and M7 without hardware floating point (ARMv7E-M architecture):
 ``` console
 $ rustup target add thumbv7em-none-eabi
 ```
 
-Cortex M4 M7 with FPU <-- STM32F3DISCOVERY
+Cortex-M4F and M7F with hardware floating point (ARMv7E-M architecture):
 ``` console
 $ rustup target add thumbv7em-none-eabihf
 ```

src/intro/install/linux.md

@@ -57,7 +57,7 @@ sudo dnf install arm-none-eabi-gdb openocd qemu-system-arm
 > Cortex-M programs
 
 ``` console
-sudo pacman -S arm-none-eabi-gdb qemu-arch-extra
+sudo pacman -S arm-none-eabi-gdb qemu-arch-extra openocd
 ```
 
 Now install openocd from [AUR](https://aur.archlinux.org/packages/openocd/)

src/intro/install/macos.md

@@ -6,7 +6,6 @@ All the tools can be install using [Homebrew]:
 
 ``` console
 $ # GDB
-$ brew tap armmbed/formulae
 $ brew install armmbed/formulae/arm-none-eabi-gcc
 
 $ # OpenOCD

src/intro/install/verify.md

@@ -60,7 +60,7 @@ you'll need to configure things a bit differently later on. You can move to the
 
 If neither command worked as a normal user then try to run them with root
 permission (e.g. `sudo openocd ..`). If the commands do work with root
-permission then check that the [udev rules] has been correctly set.
+permission then check that the [udev rules] have been correctly set.
 
 [udev rules]: linux.md#udev-rules
 

src/intro/no-std.md

@@ -11,7 +11,7 @@ There are two general Embedded Programming classifications:
 
 ## Hosted Environments
 These kinds of environments are close to a normal PC environment.
-What this means is you are provided with a System Interface [E.G. POSIX](https://en.wikipedia.org/wiki/POSIX)
+What this means is that you are provided with a System Interface [E.G. POSIX](https://en.wikipedia.org/wiki/POSIX)
 that provides you with primitives to interact with various systems, such as file systems, networking, memory management, threads, etc.
 Standard libraries in turn usually depend on these primitives to implement their functionality.
 You may also have some sort of sysroot and restrictions on RAM/ROM-usage, and perhaps some
@@ -61,5 +61,4 @@ bootstrapping (stage 0) code like bootloaders, firmware or kernels.
 [alloc-cortex-m]: https://github.com/rust-embedded/alloc-cortex-m
 
 ## See Also
-* [FAQ](https://www.rust-lang.org/en-US/faq.html#does-rust-work-without-the-standard-library)
 * [RFC-1184](https://github.com/rust-lang/rfcs/blob/master/text/1184-stabilize-no_std.md)

src/intro/tooling.md

@@ -15,21 +15,20 @@ tested.
 - OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
 - GDB with ARM support. Version 7.12 or newer highly recommended. Tested
   versions: 7.10, 7.11, 7.12 and 8.1
-- [OPTIONAL] `git` OR
-  [`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate). If you
-  have neither installed then don't worry about installing either.
+- [`cargo-generate`](https://github.com/ashleygwilliams/cargo-generate) or `git`.
+  These tools are optional but will make it easier to follow along with the book.
 
 The text below explains why we are using these tools. Installation instructions
 can be found on the next page.
 
 ## `cargo-generate` OR `git`
 
 Bare metal programs are non-standard (`no_std`) Rust programs that require some
-fiddling with the linking process to get the memory layout of the program
-right. All this requires unusual files (like linker scripts) and unusual
-settings (like linker flags). We have packaged all that for you in a template
-so that you only need to fill in the blanks such as the project name and the
-characteristics of your target hardware.
+adjustments to the linking process in order to get the memory layout of the program
+right. This requires some additional files (like linker scripts) and 
+settings (like linker flags). We have packaged those for you in a template
+such that you only need to fill in the missing information (such as the project name and the
+characteristics of your target hardware).
 
 Our template is compatible with `cargo-generate`: a Cargo subcommand for
 creating new Cargo projects from templates. You can also download the
@@ -58,7 +57,7 @@ can follow some parts of this book even if you don't have any hardware with you!
 
 A debugger is a very important component of embedded development as you may not
 always have the luxury to log stuff to the host console. In some cases, you may
-not have LEDs to blink on your hardware!
+not even have LEDs to blink on your hardware!
 
 In general, LLDB works as well as GDB when it comes to debugging but we haven't
 found an LLDB counterpart to GDB's `load` command, which uploads the program to