Merge branch 'master' into rustconf-dump

Author: jamesmunns

src/SUMMARY.md

@@ -18,7 +18,12 @@ more information and coordination
     - [Tooling](./intro/tooling.md)
     - [Hardware](./intro/hardware.md)
     - [`no_std`](./intro/no-std.md)
-- [Blinking your first LED](./blinky/blinky.md)
+- [Getting started](./start.md)
+  - [QEMU](./start/qemu.md)
+  - [Hardware](./start/hardware.md)
+  - [Panics](./start/panics.md)
+  - [Exceptions](./start/exceptions.md)
+  - [IO](./start/io.md)
 - [Peripherals](./peripherals/peripherals.md)
     - [A first attempt in Rust](./peripherals/a-first-attempt.md)
     - [The Borrow Checker](./peripherals/borrowck.md)

src/assets/verify.jpeg

@@ -1,3 +1,3 @@
 # Tips for embedded C developers
 
-> ❌: This section has not yet been written. Please refer to [embedded-wg#126](https://github.com/rust-lang-nursery/embedded-wg/issues/126) for discussion of this section.
+> ❌: This section has not yet been written. Please refer to [rust-embedded/book#9](https://github.com/rust-embedded/book/issues/9) for discussion of this section.

src/blinky/blinky.md

@@ -1,3 +1,3 @@
 # Concurrency
 
-> ❌: This section has not yet been written. Please refer to [embedded-wg#124](https://github.com/rust-lang-nursery/embedded-wg/issues/124) for discussion of this section.
+> ❌: This section has not yet been written. Please refer to [rust-embedded/book#7](https://github.com/rust-embedded/book/issues/7) for discussion of this section.

src/c-tips/c-tips.md

@@ -1,3 +1,3 @@
 # Interoperability
 
-> ❌: This section has not yet been written. Please refer to [embedded-wg#48](https://github.com/rust-lang-nursery/embedded-wg/issues/48) for discussion of this section.
+> ❌: This section has not yet been written. Please refer to [rust-embedded/book#1](https://github.com/rust-embedded/book/issues/1) for discussion of this section.

src/concurrency/concurrency.md

@@ -1,18 +1,11 @@
-> **⚠️: This section contains exports from [Japaric's Discovery] book.**
->
-> Contents should be reviewed for consistency in the context
-> of this book before "publishing"
-
-[Japaric's Discovery]: https://japaric.github.io/discovery/
-
 # Meet your hardware
 
 Let's get familiar with the hardware we'll be working with.
 
 ## STM32F3DISCOVERY (the "F3")
 
 <p align="center">
-<img title="F3" src="/book/assets/f3.jpg">
+<img title="F3" src="/assets/f3.jpg">
 </p>
 
 We'll refer to this board as "F3" throughout this book.

src/interoperability/interoperability.md

@@ -1,88 +1,90 @@
-> **⚠️: This section contains exports from [Japaric's Discovery] book.**
->
-> Contents should be reviewed for consistency in the context
-> of this book before "publishing"
-
-[Japaric's Discovery]: https://japaric.github.io/discovery/
-
-> **⚠️: This section still references `nightly` Rust**
+> **⚠️: This section still references `beta` Rust**
 >
 > Contents should be updated to work on `stable` Rust when possible
 
-> **⚠️: This section has not been checked as of 2018-07-29**
->
-> Contents should be checked to still be working with current `nightly`
-> or `stable` Rust
+> **⚠️: This section was last checked on 2018-09-13**
 
 # Setting up a development environment
 
 Dealing with microcontrollers involves several tools as we'll be dealing with an architecture
-different than your laptop's and we'll have to run and debug programs on a "remote" device.
+different than your laptop's and we'll have to run and debug programs on a *remote* device.
+
+<!-- NOTE(japaric) I'm not sure we are going to need the user to download *all* -->
+<!-- these docs so I'm going to comment out this section. If it turns out we do -->
+<!-- need some doc I think it would be best to link it from the section where -->
+<!-- it's needed -->
 
-## Documentation
+<!-- ## Documentation -->
 
-Tooling is not everything though. Without documentation is pretty much impossible to work with microcontrollers.
+<!-- Tooling is not everything though. Without documentation is pretty much impossible to work with microcontrollers. -->
 
-We'll be referring to all these documents throughout this book:
+<!-- We'll be referring to all these documents throughout this book: -->
 
-*HEADS UP* All these links point to PDF files and some of them are hundreds of pages long and
-several MBs in size.
+<!-- *HEADS UP* All these links point to PDF files and some of them are hundreds of pages long and -->
+<!-- several MBs in size. -->
 
-- [STM32F3DISCOVERY User Manual][um]
-- [STM32F303VC Datasheet][ds]
-- [STM32F303VC Reference Manual][rm]
-- [LSM303DLHC]
-- [L3GD20]
+<!-- - [STM32F3DISCOVERY User Manual][um] -->
+<!-- - [STM32F303VC Datasheet][ds] -->
+<!-- - [STM32F303VC Reference Manual][rm] -->
+<!-- - [LSM303DLHC] -->
+<!-- - [L3GD20] -->
 
-[L3GD20]: http://www.st.com/resource/en/datasheet/l3gd20.pdf
-[LSM303DLHC]: http://www.st.com/resource/en/datasheet/lsm303dlhc.pdf
-[ds]: http://www.st.com/resource/en/datasheet/stm32f303vc.pdf
-[rm]: http://www.st.com/resource/en/reference_manual/dm00043574.pdf
-[um]: http://www.st.com/resource/en/user_manual/dm00063382.pdf
+<!-- [L3GD20]: http://www.st.com/resource/en/datasheet/l3gd20.pdf -->
+<!-- [LSM303DLHC]: http://www.st.com/resource/en/datasheet/lsm303dlhc.pdf -->
+<!-- [ds]: http://www.st.com/resource/en/datasheet/stm32f303vc.pdf -->
+<!-- [rm]: http://www.st.com/resource/en/reference_manual/dm00043574.pdf -->
+<!-- [um]: http://www.st.com/resource/en/user_manual/dm00063382.pdf -->
 
 ## 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.
 
-- Cargo & `rustc` >= nightly-2018-06-04
-- [`itmdump`] v0.2.1
+- 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/rust-embedded/cargo-binutils) ~0.1.4
+- [`qemu-system-arm`](https://www.qemu.org/). Tested versions: 3.0.0
 - OpenOCD >=0.8. Tested versions: v0.9.0 and v0.10.0
-- `arm-none-eabi-gcc`. Tested version: ?.??
-- `arm-none-eabi-binutils`
-    - `arm-none-eabi-ld`. Tested version: 2.30
-    - `arm-none-eabi-gdb`. Version 7.12 or newer highly recommended. Tested versions: 7.10, 7.11,
-      7.12 and 8.1
-- `minicom` on Linux and macOS. Tested version: 2.7. Readers report that `picocom` also works but
-  we'll use `minicom` in this text.
-
-- `PuTTY` on Windows.
-
-[`itmdump`]: https://crates.io/crates/itm
+- 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.
 
 Next, follow OS-agnostic installation instructions for a few of the tools:
 
-### `rustc` & Cargo
+### Rust toolchain
 
 Install rustup by following the instructions at [https://rustup.rs](https://rustup.rs).
 
-Then, install or switch to the nightly channel.
+Then switch to the beta channel.
 
 ``` console
-$ rustup default nightly
+$ rustup default beta
 ```
 
-**NOTE** Make sure you have a nightly newer than `nightly-2018-06-04`. `rustc -V` should return a
-date newer than the one shown below:
+**NOTE** Make sure you have a beta equal to or newer than `1.30-beta`. `rustc
+-V` should return a date newer than the one shown below. If `1.30-beta` is not
+out yet then use the nightly channel for the time being.
 
 ``` console
 $ rustc -V
-rustc 1.28.0-nightly (29f48ccf3 2018-06-03)
+rustc 1.30.0-beta (????????? 2018-09-1?)
+```
+
+For bandwidth and disk usage reasons the default installation only supports
+native compilation. To add cross compilation support for the ARM Cortex-M
+architecture install the following compilation targets.
+
+``` console
+$ rustup target add thumbv6m-none-eabi thumbv7m-none-eabi thumbv7em-none-eabi thumbv7em-none-eabihf
 ```
 
-### `itmdump`
+### `cargo-binutils`
 
 ``` console
-$ cargo install itm --vers 0.2.1
+$ cargo install cargo-binutils
+
+$ rustup component add llvm-tools-preview
 ```
 
 ### OS specific instructions

src/intro/hardware.md

@@ -1,130 +1,127 @@
-> **⚠️: This section contains exports from [Japaric's Discovery] book.**
->
-> Contents should be reviewed for consistency in the context
-> of this book before "publishing"
-
-[Japaric's Discovery]: https://japaric.github.io/discovery/
-
-> **⚠️: This section has not been checked as of 2018-07-29**
->
-> Contents should be checked to still be working with current `nightly`
-> or `stable` Rust
+> **⚠️: This section was last checked on 2018-09-13
 
 # Linux
 
 Here are the installation commands for a few Linux distributions.
 
-## REQUIRED packages
+## Packages
+
+- Ubuntu 18.04 or newer / Debian stretch or newer
+
+> **NOTE** `gdb-multiarch` is the GDB command you'll use to debug your ARM
+> Cortex-M programs
+
+<!-- Debian stretch -->
+<!-- GDB 7.12 -->
+<!-- OpenOCD 0.9.0 -->
+<!-- QEMU 2.8.1 -->
 
-- Ubuntu 16.04 or newer / Debian Jessie or newer
+<!-- Ubuntu 18.04 -->
+<!-- GDB 8.1 -->
+<!-- OpenOCD 0.10.0 -->
+<!-- QEMU 2.11.1 -->
+
+``` console
+$ sudo apt-get install \
+  gdb-multiarch \
+  openocd \
+  qemu-system-arm
+```
+
+- Ubuntu 14.04 and 16.04
+
+> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM
+> Cortex-M programs
+
+<!-- Ubuntu 14.04 -->
+<!-- GDB 7.6 (!) -->
+<!-- OpenOCD 0.7.0 (?) -->
+<!-- QEMU 2.0.0 (?) -->
 
 ``` console
 $ sudo apt-get install \
-  binutils-arm-none-eabi \
   gdb-arm-none-eabi \
-  minicom \
-  openocd
+  openocd \
+  qemu-system-arm
 ```
 
-- Fedora 23 or newer
+- Fedora 27 or newer
+
+> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug your ARM
+> Cortex-M programs
+
+<!-- Fedora 27 -->
+<!-- GDB 7.6 (!) -->
+<!-- OpenOCD 0.10.0 -->
+<!-- QEMU 2.10.2 -->
 
 ``` console
 $ sudo dnf install \
-  arm-none-eabi-gcc-cs \
   arm-none-eabi-gdb \
-  minicom \
-  openocd
+  openocd \
+  qemu-system-arm
 ```
 
 - Arch Linux
 
+> **NOTE** `arm-none-eabi-gdb` is the GDB command you'll use to debug ARM
+> Cortex-M programs
+
 ``` console
 $ sudo pacman -S \
-  arm-none-eabi-gcc \
   arm-none-eabi-gdb \
-  arm-none-eabi-gcc \
-  minicom
+  qemu-system-arm
 
-$ yaourt -S openocd
+$ # install openocd from the AUR -- https://aur.archlinux.org/packages/openocd/
 ```
 
 ## udev rules
 
-These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e.
-`sudo`.
+This rule lets you use OpenOCD with the Discovery board without root privilege.
 
-Create these two files in `/etc/udev/rules.d` with the contents shown below.
+Create this file in `/etc/udev/rules.d` with the contents shown below.
 
 ``` console
-$ cat /etc/udev/rules.d/99-ftdi.rules
-```
-
-``` text
-# FT232 - USB <-> Serial Converter
-ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", GROUP="uucp"
-```
-
-``` console
-$ cat /etc/udev/rules.d/99-openocd.rules
+$ cat /etc/udev/rules.d/99-st-link.rules
 ```
 
 ``` text
 # STM32F3DISCOVERY rev A/B - ST-LINK/V2
-ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", GROUP="uucp"
+ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", MODE:="0666"
 
 # STM32F3DISCOVERY rev C+ - ST-LINK/V2-1
-ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", GROUP="uucp"
+ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", MODE:="0666"
 ```
 
-Then reload the udev rules with:
+Then reload all the udev rules with:
 
 ``` console
 $ sudo udevadm control --reload-rules
 ```
 
-If you had any board plugged to your laptop, unplug them and then plug them in again.
-
-Finally, check if you are in the `uucp` group.
-
-``` console
-$ groups $(id -nu)
-(..) uucp (..)
-$ #  ^^^^
-```
-
-(`$(id -nu)` returns your user name. In my case it's `japaric`.)
-
-If `uucp` appears in the output. You are all set! Go to the [next section]. Otherwise, keep reading:
-
-[next section]: /intro/install/verify.html
+If you had the board plugged to your laptop, unplug it and then plug it again.
 
-- Add yourself to the `uucp` group.
+You can check the permissions by running these commands:
 
 ``` console
-$ sudo usermod -a -G uucp $(id -u -n)
+$ lsusb
+(..)
+Bus 001 Device 018: ID 0483:374b STMicroelectronics ST-LINK/V2.1
+(..)
 ```
 
-- Check again the output of `groups`. `uucp` should be there this time!
+Take note of the bus and device numbers. Use those numbers in the following
+command:
 
 ``` console
-$ groups $(id -nu)
-(..) uucp (..)
-$ #  ^^^^
+$ # the format of the path is /dev/bus/usb/<bus>/<device>
+$ ls -l /dev/bus/usb/001/018
+crw-rw-rw- 1 root root 189, 17 Sep 13 12:34 /dev/bus/usb/001/018
 ```
 
-You'll have to re-log for these changes to take effect. You have two options:
-
-You can reboot or log out from your current session and then log in; this will close all the
-programs you have open right now.
-
-The other option is to use the command below:
-
-``` console
-$ su - $(id -nu)
-```
-
-to re-log *only in the current shell* and get access to `uucp` devices *only on that shell*. Other
-shells *won't* have access to `uucp` devices unless you manually re-log on them with the same `su`
-command.
+The permissions should be `crw-rw-rw-`; this indicates that all users can make
+use of this device.
 
 Now, go to the [next section].
+
+[next section]: /intro/install/verify.html