Merge branch 'master' of https://github.com/rust-embedded/book

src/concurrency/index.md

@@ -42,7 +42,7 @@ you can get away with such a simple approach this can be a great solution.
 
 Unlike non-embedded Rust, we will not usually have the luxury of creating
 heap allocations and passing references to that data into a newly-created
-thread. Instead our interrupt handlers might be called at any time and must
+thread. Instead, our interrupt handlers might be called at any time and must
 know how to access whatever shared memory we are using. At the lowest level,
 this means we must have _statically allocated_ mutable memory, which
 both the interrupt handler and the main code can refer to.
@@ -124,7 +124,7 @@ fn timer() {
 }
 ```
 
-In this example we use `cortex_m::interrupt::free`, but other platforms will
+In this example, we use `cortex_m::interrupt::free`, but other platforms will
 have similar mechanisms for executing code in a critical section. This is also
 the same as disabling interrupts, running some code, and then re-enabling
 interrupts.
@@ -138,7 +138,7 @@ for two reasons:
 If `COUNTER` was being shared by multiple interrupt handlers that might
 _preempt_ each other, then each one might require a critical section as well.
 
-This solves our immediate problem, but we're still left writing a lot of unsafe code which we need to carefully reason about, and we might be using critical sections needlessly. Since each critical section temporarily pauses interrupt processing, there is an associated cost of some extra code size and higher interrupt latency and jitter (interrupts may take longer to be processed, and the time until they are processed will be more variable). Whether this is a problem depends on your system, but in general we'd like to avoid it.
+This solves our immediate problem, but we're still left writing a lot of unsafe code which we need to carefully reason about, and we might be using critical sections needlessly. Since each critical section temporarily pauses interrupt processing, there is an associated cost of some extra code size and higher interrupt latency and jitter (interrupts may take longer to be processed, and the time until they are processed will be more variable). Whether this is a problem depends on your system, but in general, we'd like to avoid it.
 
 It's worth noting that while a critical section guarantees no interrupts will
 fire, it does not provide an exclusivity guarantee on multi-core systems!  The
@@ -209,7 +209,7 @@ blocks which must be very carefully checked and are not ergonomic. Surely we
 can do better in Rust!
 
 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
+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,ignore
@@ -274,7 +274,7 @@ fn timer() {
 We've moved our `unsafe` code to inside our carefully-planned abstraction,
 and now our application code does not contain any `unsafe` blocks.
 
-This design requires the application pass a `CriticalSection` token in:
+This design requires that the application pass a `CriticalSection` token in:
 these tokens are only safely generated by `interrupt::free`, so by requiring
 one be passed in, we ensure we are operating inside a critical section, without
 having to actually do the lock ourselves. This guarantee is provided statically
@@ -302,7 +302,7 @@ variables _must_ be Sync, since they can be accessed by multiple threads.
 To tell the compiler we have taken care that the `CSCounter` is in fact safe
 to share between threads, we implement the Sync trait explicitly. As with the
 previous use of critical sections, this is only safe on single-core platforms:
-with multiple cores you would need to go to greater lengths to ensure safety.
+with multiple cores, you would need to go to greater lengths to ensure safety.
 
 ## Mutexes
 
@@ -383,8 +383,8 @@ to get a safe counter with no unsafe code at all!
 
 This is great for simple types like the `u32` of our counter, but what about
 more complex types which are not Copy? An extremely common example in an
-embedded context is a peripheral struct, which generally are not Copy.
-For that we can turn to `RefCell`.
+embedded context is a peripheral struct, which generally is not Copy.
+For that, we can turn to `RefCell`.
 
 ## Sharing Peripherals
 
@@ -499,7 +499,7 @@ interrupt::free(|cs| {
 });
 ```
 
-Finally we use `MY_GPIO` in a safe and concurrent fashion. The critical section
+Finally, we use `MY_GPIO` in a safe and concurrent fashion. The critical section
 prevents the interrupt firing as usual, and lets us borrow the mutex.  The
 `RefCell` then gives us an `&Option<GPIOA>`, and tracks how long it remains
 borrowed - once that reference goes out of scope, the `RefCell` will be updated
@@ -509,7 +509,7 @@ Since we can't move the `GPIOA` out of the `&Option`, we need to convert it to
 an `&Option<&GPIOA>` with `as_ref()`, which we can finally `unwrap()` to obtain
 the `&GPIOA` which lets us modify the peripheral.
 
-If we need a mutable references to shared resources, then `borrow_mut` and `deref_mut`
+If we need a mutable reference to a shared resource, then `borrow_mut` and `deref_mut`
 should be used instead. The following code shows an example using the TIM2 timer.
 
 ```rust,ignore
@@ -587,7 +587,7 @@ primitives, and often interoperate with hardware features such as DMA engines.
 [FreeRTOS]: https://freertos.org/
 [ChibiOS]: http://chibios.org/
 
-At the time of writing there are not many Rust RTOS examples to point to,
+At the time of writing, there are not many Rust RTOS examples to point to,
 but it's an interesting area so watch this space!
 
 ## Multiple Cores

src/start/exceptions.md

@@ -62,7 +62,7 @@ times it has been called in the `COUNT` variable and then prints the value of
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use core::fmt::Write;
 
@@ -190,7 +190,7 @@ memory location.
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use core::fmt::Write;
 use core::ptr;

src/start/panicking.md

@@ -51,11 +51,11 @@ profile. For example:
 
 // dev profile: easier to debug panics; can put a breakpoint on `rust_begin_unwind`
 #[cfg(debug_assertions)]
-extern crate panic_halt;
+use panic_halt as _;
 
 // release profile: minimize the binary size of the application
 #[cfg(not(debug_assertions))]
-extern crate panic_abort;
+use panic_abort as _;
 
 // ..
 ```
@@ -64,6 +64,13 @@ In this example the crate links to the `panic-halt` crate when built with the
 dev profile (`cargo build`), but links to the `panic-abort` crate when built
 with the release profile (`cargo build --release`).
 
+> The `use panic_abort as _;` form of the `use` statement is used to ensure the `panic_abort` panic handler is
+> included in our final executable while making it clear to the compiler that we won't explicitly use anything from
+> the crate. Without the `as _` rename, the compiler would warn that we have an unused import.
+> Sometimes you might see `extern crate panic_abort` instead, which is an older style used before the
+> 2018 edition of Rust, and should now only be used for "sysroot" crates (those distributed with Rust itself) such
+> as `proc_macro`, `alloc`, `std`, and `test`.
+
 ## An example
 
 Here's an example that tries to index an array beyond its length. The operation
@@ -73,7 +80,7 @@ results in a panic.
 #![no_main]
 #![no_std]
 
-extern crate panic_semihosting;
+use panic_semihosting as _;
 
 use cortex_m_rt::entry;
 

src/start/qemu.md

@@ -94,7 +94,7 @@ For convenience here are the most important parts of the source code in `src/mai
 #![no_std]
 #![no_main]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m_rt::entry;
 
@@ -117,7 +117,7 @@ interface that most Rust programs use. The main (no pun intended) reason to go
 with `no_main` is that using the `main` interface in `no_std` context requires
 nightly.
 
-`extern crate panic_halt;`. This crate provides a `panic_handler` that defines
+`use panic_halt as _;`. This crate provides a `panic_handler` that defines
 the panicking behavior of the program. We will cover this in more detail in the
 [Panicking](panicking.md) chapter of the book.
 
@@ -318,7 +318,7 @@ For convenience here's the source code of `examples/hello.rs`:
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m_rt::entry;
 use cortex_m_semihosting::{debug, hprintln};
@@ -509,7 +509,7 @@ list main
 This will show the source code, from the file examples/hello.rs. 
 
 ```text
-6       extern crate panic_halt;
+6       use panic_halt as _;
 7
 8       use cortex_m_rt::entry;
 9       use cortex_m_semihosting::{debug, hprintln};

src/start/registers.md

@@ -66,7 +66,8 @@ We won't get very far with our embedded software development if we restrict ours
 #![no_std]
 #![no_main]
 
-use panic_halt as _;
+
+use panic_halt as _; // panic handler
 
 use cortex_m_rt::entry;
 use tm4c123x;
@@ -142,7 +143,7 @@ Let's see an example:
 #![no_std]
 #![no_main]
 
-use panic_halt as _;
+use panic_halt as _; // panic handler
 
 use cortex_m_rt::entry;
 use tm4c123x_hal as hal;

src/start/semihosting.md

@@ -16,7 +16,7 @@ world!":
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m_rt::entry;
 use cortex_m_semihosting::hprintln;
@@ -67,7 +67,7 @@ until you restart it.
 #![no_main]
 #![no_std]
 
-extern crate panic_halt;
+use panic_halt as _;
 
 use cortex_m_rt::entry;
 use cortex_m_semihosting::debug;
@@ -105,7 +105,7 @@ stderr.
 #![no_main]
 #![no_std]
 
-extern crate panic_semihosting; // features = ["exit"]
+use panic_semihosting as _; // features = ["exit"]
 
 use cortex_m_rt::entry;
 use cortex_m_semihosting::debug;