prepare for beta

japaric · japaric · commit 508802f48254 · 2018-09-14T22:02:18.000+02:00
this commit removes features gate from the code and from Cargo.toml

it also makes use of the new `--edition` flag to simplify the instructions for
creating a new project
diff --git a/ci/exceptions/app/Cargo.toml b/ci/exceptions/app/Cargo.toml
@@ -1,5 +1,3 @@
-cargo-features = ["edition"]
-
 [package]
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
 edition = "2018"
diff --git a/ci/exceptions/rt/src/lib.rs b/ci/exceptions/rt/src/lib.rs
@@ -1,4 +1,3 @@
-#![feature(panic_handler)]
 #![no_std]
 
 use core::panic::PanicInfo;
diff --git a/ci/main/app/Cargo.toml b/ci/main/app/Cargo.toml
@@ -1,7 +1,5 @@
-cargo-features = ["edition"] # <-
-
 [package]
-edition = "2018" # <-
+edition = "2018"
 name = "app"
 version = "0.1.0"
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
diff --git a/ci/main/app4/Cargo.toml b/ci/main/app4/Cargo.toml
@@ -1,5 +1,3 @@
-cargo-features = ["edition"]
-
 [package]
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
 edition = "2018"
diff --git a/ci/main/rt/Cargo.toml b/ci/main/rt/Cargo.toml
@@ -1,9 +1,7 @@
-cargo-features = ["edition"]
-
 [package]
-name = "rt" # <-
-authors = ["Jorge Aparicio <jorge@japaric.io>"]
 edition = "2018"
+name = "rt" # <-
 version = "0.1.0"
+authors = ["Jorge Aparicio <jorge@japaric.io>"]
 
 [dependencies]
diff --git a/ci/main/rt/src/lib.rs b/ci/main/rt/src/lib.rs
@@ -1,4 +1,3 @@
-#![feature(panic_handler)]
 #![no_std]
 
 use core::panic::PanicInfo;
diff --git a/ci/main/rt2/src/lib.rs b/ci/main/rt2/src/lib.rs
@@ -1,4 +1,3 @@
-#![feature(panic_handler)]
 #![no_std]
 
 use core::panic::PanicInfo;
diff --git a/ci/memory-layout/src/main.rs b/ci/memory-layout/src/main.rs
@@ -1,4 +1,3 @@
-#![feature(panic_handler)]
 #![no_main]
 #![no_std]
 
diff --git a/ci/smallest-no-std/Cargo.toml b/ci/smallest-no-std/Cargo.toml
@@ -1,7 +1,5 @@
-cargo-features = ["edition"] # <-
-
 [package]
-edition = "2018" # <-
+edition = "2018"
 name = "app"
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
 version = "0.1.0"
diff --git a/ci/smallest-no-std/src/main.rs b/ci/smallest-no-std/src/main.rs
@@ -1,4 +1,3 @@
-#![feature(panic_handler)]
 #![no_main]
 #![no_std]
 
diff --git a/src/exceptions.md b/src/exceptions.md
@@ -43,11 +43,11 @@ The first thing we'll do is create an array of vectors (pointers to exception ha
 `rt` crate's code:
 
 ``` console
-$ sed -n 57,92p ../rt/src/lib.rs
+$ sed -n 56,91p ../rt/src/lib.rs
 ```
 
 ``` rust
-{{#include ../ci/exceptions/rt/src/lib.rs:57:92}}
+{{#include ../ci/exceptions/rt/src/lib.rs:56:91}}
 ```
 
 Some of the entries in the vector table are *reserved*; the ARM documentation states that they
@@ -63,7 +63,7 @@ $ tail -n4 ../rt/src/lib.rs
 ```
 
 ``` rust
-{{#include ../ci/exceptions/rt/src/lib.rs:94:97}}
+{{#include ../ci/exceptions/rt/src/lib.rs:93:97}}
 ```
 
 ## Linker script side
@@ -105,24 +105,31 @@ handler for the respective exception.
 That's it! The `rt` crate now has support for exception handlers. We can test it out with following
 application:
 
+> **NOTE**: Turns out it's hard to generate an exception in QEMU. On real
+> hardware a read to an invalid memory address (i.e. outside of the Flash and
+> RAM regions) would be enough but QEMU happily accepts the operation and
+> returns zero. A trap instruction works on both QEMU and hardware but
+> unfortunately it's not available on stable so you'll have to temporarily
+> switch to nightly to run this and the next example.
+
 ``` rust
 {{#include ../ci/exceptions/app/src/main.rs}}
 ```
 
 ``` console
 (lldb) b DefaultExceptionHandler
-Breakpoint 1: where = app`DefaultExceptionHandler at lib.rs:96, address = 0x000000ec
+Breakpoint 1: where = app`DefaultExceptionHandler at lib.rs:95, address = 0x000000ec
 
 (lldb) continue
 Process 1 resuming
 Process 1 stopped
 * thread #1, stop reason = breakpoint 1.1
-    frame #0: 0x000000ec app`DefaultExceptionHandler at lib.rs:96
-   93
-   94   #[no_mangle]
-   95   pub extern "C" fn DefaultExceptionHandler() {
--> 96       loop {}
-   97   }
+    frame #0: 0x000000ec app`DefaultExceptionHandler at lib.rs:95
+   92
+   93   #[no_mangle]
+   94   pub extern "C" fn DefaultExceptionHandler() {
+-> 95       loop {}
+   96   }
 ```
 
 And for completeness, here's the disassembly of the optimized version of the program:
@@ -220,12 +227,12 @@ You can test it in QEMU
 Process 1 resuming
 Process 1 stopped
 * thread #1, stop reason = breakpoint 1.1
-    frame #0: 0x00000044 app`HardFault at main.rs:19
-   16   #[no_mangle]
-   17   pub extern "C" fn HardFault() -> ! {
-   18       // do something interesting here
--> 19       loop {}
-   20   }
+    frame #0: 0x00000044 app`HardFault at main.rs:18
+   15   #[no_mangle]
+   16   pub extern "C" fn HardFault() -> ! {
+   17       // do something interesting here
+-> 18       loop {}
+   19   }
 ```
 
 The program now executes the user defined `HardFault` function instead of the
@@ -234,6 +241,8 @@ The program now executes the user defined `HardFault` function instead of the
 Like our first attempt at a `main` interface, this first implementation has the problem of having no
 type safety. It's also easy to mistype the name of the exception, but that doesn't produce an error
 or warning. Instead the user defined handler is simply ignored. Those problems can be fixed using a
-macro like the [`exception!`] macro defined in `cortex-m-rt`.
+macro like the [`exception!`] macro defined in `cortex-m-rt` v0.5.x or the
+[`exception`] attribute in `cortex-m-rt` v0.6.x.
 
-[`exception!`]: https://github.com/japaric/cortex-m-rt/blob/v0.5.1/src/lib.rs#L79
+[`exception!`]: https://github.com/japaric/cortex-m-rt/blob/v0.5.1/src/lib.rs#L792
+[`exception`]: https://github.com/rust-embedded/cortex-m-rt/blob/v0.6.3/macros/src/lib.rs#L254
diff --git a/src/main.md b/src/main.md
@@ -15,21 +15,21 @@ And then rename it to `rt` which stands for "runtime".
 ``` console
 $ sed -i s/app/rt/ Cargo.toml
 
-$ head -n5 Cargo.toml
+$ head -n4 Cargo.toml
 ```
 
 ``` toml
-{{#include ../ci/main/rt/Cargo.toml:1:5}}
+{{#include ../ci/main/rt/Cargo.toml:1:4}}
 ```
 
 The first change is to have the reset handler call an external `main` function:
 
 ``` console
-$ head -n14 src/lib.rs
+$ head -n13 src/lib.rs
 ```
 
 ``` rust
-{{#include ../ci/main/rt/src/lib.rs:1:14}}
+{{#include ../ci/main/rt/src/lib.rs:1:13}}
 ```
 
 We also drop the `#![no_main]` attribute has it has no effect on library crates.
@@ -63,19 +63,10 @@ The `rt` will take care of giving the program the right memory layout.
 ``` console
 $ cd ..
 
-$ cargo new --bin app
+$ cargo new --edition 2018 --bin app
 
 $ cd app
 
-$ # again, don't forget to move the project to the 2018 edition
-$ head -n5 Cargo.toml
-```
-
-``` toml
-{{#include ../ci/main/app/Cargo.toml:1:5}}
-```
-
-``` console
 $ cargo add rt --path ../rt
 
 $ # copy over the config file that sets a default target and tweaks the linker invocation
@@ -113,7 +104,7 @@ $ tail -n12 ../rt/src/lib.rs
 ```
 
 ``` rust
-{{#include ../ci/main/rt/src/lib.rs:26:37}}
+{{#include ../ci/main/rt/src/lib.rs:25:37}}
 ```
 
 Then the application writers can invoke it like this:
@@ -224,7 +215,7 @@ $ head -n32 ../rt/src/lib.rs
 ```
 
 ``` rust
-{{#include ../ci/main/rt2/src/lib.rs:1:32}}
+{{#include ../ci/main/rt2/src/lib.rs:1:31}}
 ```
 
 Now end users can directly and indirectly make use of `static` variables without running into
diff --git a/src/memory-layout.md b/src/memory-layout.md
@@ -246,21 +246,21 @@ $ lldb target/thumbv7m-none-eabi/debug/app
 (lldb) gdb-remote 3333
 Process 1 stopped
 * thread #1, stop reason = signal SIGTRAP
-    frame #0: 0x00000008 app`Reset at main.rs:23
-   20
-   21   #[panic_handler]
-   22   fn panic(_panic: &PanicInfo) -> ! {
--> 23       loop {}
-   24   }
+    frame #0: 0x00000008 app`Reset at main.rs:22
+   19
+   20   #[panic_handler]
+   21   fn panic(_panic: &PanicInfo<'_>) -> ! {
+-> 22       loop {}
+   23   }
 
 (lldb) # ^ that source is wrong; the processor is about to execute Reset; see below
 (lldb) disassemble -frame
 app`Reset:
 ->  0x8 <+0>:  sub    sp, #0x4
     0xa <+2>:  movs   r0, #0x2a
     0xc <+4>:  str    r0, [sp]
-    0xe <+6>:  b      0x10                      ; <+8> at main.rs:13
-    0x10 <+8>: b      0x10                      ; <+8> at main.rs:13
+    0xe <+6>:  b      0x10                      ; <+8> at main.rs:12
+    0x10 <+8>: b      0x10                      ; <+8> at main.rs:12
 
 (lldb) # the SP has the initial value we programmed in the vector table
 (lldb) print/x $sp
diff --git a/src/preface.md b/src/preface.md
@@ -37,49 +37,54 @@ This book mainly targets to two audiences:
 
 ### Requirements
 
-This book is self contained. The reader doesn't need to be familiar with the Cortex-M architecture,
-nor is access to a Cortex-M microcontroller needed -- all the examples included in this book can be tested in
-QEMU. You will, however, need to install the following tools to run and inspect the examples in this
+This book is self contained. The reader doesn't need to be familiar with the
+Cortex-M architecture, nor is access to a Cortex-M microcontroller needed -- all
+the examples included in this book can be tested in QEMU. You will, however,
+need to install the following tools to run and inspect the examples in this
 book:
 
 - All the code in this book uses the 2018 edition. If you are not familiar with
-the 2018 features and idioms check [the edition guide]. Please also note that
-until the 2018 edition is officially released you'll have to *manually modify
-the Cargo.toml of new projects* to make use the 2018 edition. The required
-changes are shown below:
-
-[the edition guide]: https://rust-lang-nursery.github.io/edition-guide/
-
-``` diff
-+cargo-features = ["edition"]
-+
- [package]
-+edition = "2018"
- name = "hello"
- version = "0.1.0"
-```
+  the 2018 features and idioms check [the edition guide].
 
-- A nightly toolchain from 2018-08-28 or newer.
+- Rust 1.30, 1.30-beta, nightly-2018-09-13, or a newer toolchain PLUS ARM
+  Cortex-M compilation support.
 
-- [`cargo-binutils`](https://github.com/japaric/cargo-binutils). v0.1.2 or newer.
+- [`cargo-binutils`](https://github.com/japaric/cargo-binutils). v0.1.4 or newer.
 
 - [`cargo-edit`](https://crates.io/crates/cargo-edit).
 
-- The `thumbv7m-none-eabi` target.
+- QEMU with support for ARM emulation. The `qemu-system-arm` program must be
+  installed on your computer.
+
+- LLDB. GDB with ARM support can also be used, but this book chooses LLDB as
+  it's more likely that readers that are not into Cortex-M development have
+  installed LLDB than GDB with ARM support.
+
+#### Example setup on Ubuntu 18.04
+
+``` console
+$ # Rust toolchain
+$ # If you start from scratch, get rustup from https://rustup.rs/
+$ rustup default beta
+
+$ rustc -V
+rustc 1.30.0-beta (????????? 2018-09-1?)
 
-- QEMU with support for ARM emulation. The `qemu-system-arm` program must be installed on your
-  computer. The name may differ for non-Debian based distributions.
+$ rustup target add thumbv7m-none-eabi
 
-- LLDB. GDB with ARM support can also be used, but this book chooses LLDB as it's more likely that
-  readers that are not into Cortex-M development have installed LLDB than GDB with ARM support.
+$ # cargo-binutils
+$ cargo install cargo-binutils
 
-  #### Rust toolchain setup on Linux
+$ rustup component add llvm-tools-preview
 
-  ```bash
-  rustup default nightly # If you start from scratch, get rustup from https://rustup.rs/
-  rustup target add thumbv7m-none-eabi
-  cargo install cargo-binutils
-  rustup component add llvm-tools-preview
-  sudo apt-get install libssl-dev # For Debian based systems (Ubuntu)
-  cargo install cargo-edit
-  ```
+$ # cargo-edit
+$ sudo apt-get install gcc libssl-dev pkg-config
+
+$ cargo install cargo-edit
+
+$ # QEMU
+$ sudo apt-get install qemu-system-arm
+
+$ # LLDB
+$ sudo apt-get install lldb
+```
diff --git a/src/smallest-no-std.md b/src/smallest-no-std.md
@@ -40,16 +40,9 @@ runs on a system. It can be many things that a standard Rust application can nev
 With that out of the way, we can move on to the smallest `#![no_std]` program that compiles:
 
 ``` console
-$ cargo new --bin app
+$ cargo new --edition 2018 --bin app
 
 $ cd app
-
-$ # don't forget to move the project to the 2018 edition
-$ head -n5 Cargo.toml
-```
-
-``` toml
-{{#include ../ci/smallest-no-std/Cargo.toml:1:5}}
 ```
 
 ``` console
@@ -77,8 +70,6 @@ indexing).
 This program doesn't produce anything useful. In fact, it will produce an empty binary.
 
 ``` console
-$ cargo rustc --target thumbv7m-none-eabi -- --emit=obj
-
 $ # equivalent to `size target/thumbv7m-none-eabi/debug/app`
 $ cargo size --target thumbv7m-none-eabi --bin app
 ```
@@ -87,7 +78,11 @@ $ cargo size --target thumbv7m-none-eabi --bin app
 {{#include ../ci/smallest-no-std/app.size}}
 ```
 
+Before linking the crate does contain the panicking symbol.
+
 ``` console
+$ cargo rustc --target thumbv7m-none-eabi -- --emit=obj
+
 $ cargo nm -- target/thumbv7m-none-eabi/debug/deps/app-*.o | grep '[0-9]* [^n] '
 ```
 

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,3 @@`
`1`		`-cargo-features = ["edition"]`
`2`		`-`
`3`	`1`	`[package]`
`4`	`2`	`authors = ["Jorge Aparicio <jorge@japaric.io>"]`
`5`	`3`	`edition = "2018"`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-#![feature(panic_handler)]`
`2`	`1`	`#![no_std]`
`3`	`2`
`4`	`3`	`use core::panic::PanicInfo;`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,3 @@`
`1`		`-#![feature(panic_handler)]`
`2`	`1`	`#![no_main]`
`3`	`2`	`#![no_std]`
`4`	`3`