diff --git a/books/embedded-rust-book/src/SUMMARY.md b/books/embedded-rust-book/src/SUMMARY.md index c3650eb5..065c6409 100644 --- a/books/embedded-rust-book/src/SUMMARY.md +++ b/books/embedded-rust-book/src/SUMMARY.md @@ -1,38 +1,36 @@ # Summary + + - [Introduction](./intro/introduction.md) - - [Preconditions](./intro/preconditions.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) - [Tooling](./intro/tooling.md) - [Hardware](./intro/hardware.md) + - [`no_std`](./intro/no-std.md) - [Blinking your first LED](./blinky/blinky.md) - - [Project Setup](./blinky/setup.md) - - [Writing](./blinky/writing.md) - - [Compiling](./blinky/compiling.md) - - [Linking](./blinky/linking.md) - - [Running and Debugging](./blinky/run-and-debug.md) -- [The `Embedded-HAL` Ecosystem](./embedded-hal/embedded-hal.md) - - [Register Definition Crates](./embedded-hal/rdc.md) - - [Chip Support Crates](./embedded-hal/csp.md) - - [`Embedded-HAL` Traits](./embedded-hal/traits.md) - - [Driver Crates](./embedded-hal/drivers.md) - - [Board Support Crates](./embedded-hal/bsp.md)- - - [Your Application Code](./embedded-hal/application.md) - - [Changing Targets](./embedded-hal/changing-targets.md) - - [RTFM: An `Embedded-HAL` based RTOS](./embedded-hal/rtfm.md) -- [The `Tock-OS` Ecosystem](./tock/tock-os.md) -- [Interoperability with existing codebases](./interop/interop.md) - - [A little C with your Rust](./interop/a-little-c.md) - - [A little Rust with your C](./interop/a-little-rust.md) - - [Using Cargo as the primary build system](./interop/build-with-cargo.md) - - [Using Cargo as a secondary build system](./interop/build-with-not-cargo.md) - - [Integrating with FreeRTOS](./interop/freertos.md) -- [Testing your embedded project](./testing/testing.md) - -- [Unsorted](./unsorted/unsorted.md) - - [Embracing Abstractions](./unsorted/abstractions.md) - - [Unlearning Bad Embedded Habits](./unsorted/unlearning.md) - - [Proper use of `unsafe`](./unsorted/unsafe.md) - - [Things we don't know how to do yet](./unsorted/unknown.md) - - [Embedded Linux](./unsorted/embedded-linux.md) - - [Glossary](./unsorted/glossary.md) \ No newline at end of file +- [Static Guarantees](./static-guarantees/static-guarantees.md) + +- [Portability](./portability/portability.md) + +- [Singletons](./singletons/singletons.md) + +- [Concurrency](./concurrency/concurrency.md) + +- [Dynamic Data Structures](./dynamic/dynamic.md) + +- [Tips for embedded C developers](./c-tips/c-tips.md) + +- [Interoperability](./interoperability/interoperability.md) + - [A little C with your Rust](./interoperability/c-with-rust.md) + - [A little Rust with your C](./interoperability/rust-with-c.md) diff --git a/books/embedded-rust-book/src/assets/f3.jpg b/books/embedded-rust-book/src/assets/f3.jpg new file mode 100644 index 00000000..7a122aa0 Binary files /dev/null and b/books/embedded-rust-book/src/assets/f3.jpg differ diff --git a/books/embedded-rust-book/src/blinky/blinky.md b/books/embedded-rust-book/src/blinky/blinky.md index c3db278e..16786bfb 100644 --- a/books/embedded-rust-book/src/blinky/blinky.md +++ b/books/embedded-rust-book/src/blinky/blinky.md @@ -1,7 +1,3 @@ # Blinking your first LED -> **This section should cover:** -> -> * This section should be an intro using (ideally) NO external crates on how to blink an LED in as few steps as possible -> * It should be a step by step guide that introduces parts of Rust tooling that are not common to desktop programs -> * It should also introduce the concept of using `unsafe` to manually dereference raw pointers to talk to a peripheral +> ❌: This section has not yet been written. Please refer to [embedded-wg#117](https://github.com/rust-lang-nursery/embedded-wg/issues/117) for discussion of this section. \ No newline at end of file diff --git a/books/embedded-rust-book/src/blinky/compiling.md b/books/embedded-rust-book/src/blinky/compiling.md deleted file mode 100644 index 16856e35..00000000 --- a/books/embedded-rust-book/src/blinky/compiling.md +++ /dev/null @@ -1,6 +0,0 @@ -# Compiling - -> **This section should cover:** -> -> * How to compile -> * Whatever errors are produced because we dont have a linker script (yet) \ No newline at end of file diff --git a/books/embedded-rust-book/src/blinky/linking.md b/books/embedded-rust-book/src/blinky/linking.md deleted file mode 100644 index 81d2db93..00000000 --- a/books/embedded-rust-book/src/blinky/linking.md +++ /dev/null @@ -1,6 +0,0 @@ -# Linking - -> **This section should cover:** -> -> * Adding a linker script to the project -> * Informing Cargo about the linker script \ No newline at end of file diff --git a/books/embedded-rust-book/src/blinky/run-and-debug.md b/books/embedded-rust-book/src/blinky/run-and-debug.md deleted file mode 100644 index f5b853ea..00000000 --- a/books/embedded-rust-book/src/blinky/run-and-debug.md +++ /dev/null @@ -1,7 +0,0 @@ -# Running and Debugging - -> **This section should cover:** -> -> * Using `openocd` and `gdb` to connect to the target -> * Uploading the firmware to the target -> * Stepping through the code on the target \ No newline at end of file diff --git a/books/embedded-rust-book/src/blinky/setup.md b/books/embedded-rust-book/src/blinky/setup.md deleted file mode 100644 index 506c292a..00000000 --- a/books/embedded-rust-book/src/blinky/setup.md +++ /dev/null @@ -1,8 +0,0 @@ -# Project Setup - -> **This section should cover:** -> -> * From a blank folder to a new cargo project -> * `.cargo/config` and necessary contents -> * `Cargo.toml` oddities -> * `Xargo.toml`, if necessary for now \ No newline at end of file diff --git a/books/embedded-rust-book/src/blinky/writing.md b/books/embedded-rust-book/src/blinky/writing.md deleted file mode 100644 index 7467d676..00000000 --- a/books/embedded-rust-book/src/blinky/writing.md +++ /dev/null @@ -1,7 +0,0 @@ -# Writing - -> **This section should cover:** -> -> * Any code necessary to add to blink an LED -> * What the code we added means (remember, we have experienced developers here) -> * Note similarities with writing desktop rust code \ No newline at end of file diff --git a/books/embedded-rust-book/src/c-tips/c-tips.md b/books/embedded-rust-book/src/c-tips/c-tips.md new file mode 100644 index 00000000..2cbb24e7 --- /dev/null +++ b/books/embedded-rust-book/src/c-tips/c-tips.md @@ -0,0 +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. \ No newline at end of file diff --git a/books/embedded-rust-book/src/concurrency/concurrency.md b/books/embedded-rust-book/src/concurrency/concurrency.md new file mode 100644 index 00000000..27458d94 --- /dev/null +++ b/books/embedded-rust-book/src/concurrency/concurrency.md @@ -0,0 +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. \ No newline at end of file diff --git a/books/embedded-rust-book/src/dynamic/dynamic.md b/books/embedded-rust-book/src/dynamic/dynamic.md new file mode 100644 index 00000000..a3e30e90 --- /dev/null +++ b/books/embedded-rust-book/src/dynamic/dynamic.md @@ -0,0 +1,3 @@ +# Dynamic Data Structures + +> ❌: This section has not yet been written. Please refer to [embedded-wg#125](https://github.com/rust-lang-nursery/embedded-wg/issues/125) for discussion of this section. \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/application.md b/books/embedded-rust-book/src/embedded-hal/application.md deleted file mode 100644 index 7b712253..00000000 --- a/books/embedded-rust-book/src/embedded-hal/application.md +++ /dev/null @@ -1,12 +0,0 @@ -# Your Application Code - -> **This section should cover:** -> -> * Writing a fancier application using all the stuff we've learned -> * Best practices for structuring a project -> * Integrating other crates, including -> * more drivers -> * `#[no_std]` crates (maybe `serde` or similar?) -> * Using `embedded-hal` traits for portability -> * Allocators? -> * More powerful parts of the `core` language? Iterators? Matching, etc? \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/bsp.md b/books/embedded-rust-book/src/embedded-hal/bsp.md deleted file mode 100644 index e7726583..00000000 --- a/books/embedded-rust-book/src/embedded-hal/bsp.md +++ /dev/null @@ -1,8 +0,0 @@ -# Board Support Crates - -> **This section should cover:** -> -> * BSPs are just specialized CSPs + specific drivers -> * Useful for development boards -> * Probably worth building for your own projects -> * Simpler blinky (vs CSP), because certain things are "hardwired", and drivers are already included \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/changing-targets.md b/books/embedded-rust-book/src/embedded-hal/changing-targets.md deleted file mode 100644 index 8aecaffd..00000000 --- a/books/embedded-rust-book/src/embedded-hal/changing-targets.md +++ /dev/null @@ -1,7 +0,0 @@ -# Changing Targets - -> **This section should cover:** -> -> * Moving from one target to a dissimilar target, e.g. `stm32xxx` to `nrf5x` -> * Demonstrate how stuff based on `embedded-hal` still works -> * Code reuse ftw \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/csp.md b/books/embedded-rust-book/src/embedded-hal/csp.md deleted file mode 100644 index dda228d1..00000000 --- a/books/embedded-rust-book/src/embedded-hal/csp.md +++ /dev/null @@ -1,9 +0,0 @@ -# Chip Support Crates - -> **This section should cover:** -> -> * What is a Chip Support Crate? -> * Why does it have to be written by a person (unlike RDCs) -> * What is possible with a Chip Support Crate? -> * A slightly better blinky with the CSP for our demo board -> * Maybe mention CSPs for families \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/drivers.md b/books/embedded-rust-book/src/embedded-hal/drivers.md deleted file mode 100644 index 4e5330ef..00000000 --- a/books/embedded-rust-book/src/embedded-hal/drivers.md +++ /dev/null @@ -1,7 +0,0 @@ -# Driver Crates - -> **This section should cover:** -> -> * Why base drivers off of Embedded-HAL traits? -> * Who writes Embedded HAL drivers? -> * What kind of things are possible, or are not possible using shared drivers? \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/embedded-hal.md b/books/embedded-rust-book/src/embedded-hal/embedded-hal.md deleted file mode 100644 index 9dca81f7..00000000 --- a/books/embedded-rust-book/src/embedded-hal/embedded-hal.md +++ /dev/null @@ -1,9 +0,0 @@ -# The Embedded-HAL Ecosystem - -> **This section should cover:** -> -> * Explain the layers in the embedded-hal ecosystem -> * Slowly building from the ground up through the layers, showing examples of usage at each layer -> * Where each layer comes from (who writes it, and how) -> * Any concepts introduced at each layer -> * Link out to the embeddednomicon for how to write in more detail \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/rdc.md b/books/embedded-rust-book/src/embedded-hal/rdc.md deleted file mode 100644 index 6a8a2838..00000000 --- a/books/embedded-rust-book/src/embedded-hal/rdc.md +++ /dev/null @@ -1,10 +0,0 @@ -# Register Definition Crates - -> **This section should cover:** -> -> * What is a Register Definition Crate? -> * SVDs and `svd2rust` - generating Register Definition Crates -> * You don't have to use `svd2rust`, but you probably want to -> * What is possible with just a register definition crate? -> * A slightly better blinky using the types defined by the RDC for the board we will use -> * Maybe mention "family" crates, for info shared between families of chips \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/rtfm.md b/books/embedded-rust-book/src/embedded-hal/rtfm.md deleted file mode 100644 index ce234ee9..00000000 --- a/books/embedded-rust-book/src/embedded-hal/rtfm.md +++ /dev/null @@ -1,8 +0,0 @@ -# RTFM: An Embedded-HAL based RTOS - -> **This section should cover:** -> -> * TL;DR of RTFM, the design choices it makes, and how it integrates with `embedded-hal` ecosystem -> * Why you might want to use RTFM -> * Why you might not want to use RTFM -> * Where to learn more about RTFM (not covered in this guide) \ No newline at end of file diff --git a/books/embedded-rust-book/src/embedded-hal/traits.md b/books/embedded-rust-book/src/embedded-hal/traits.md deleted file mode 100644 index 0f0b75c8..00000000 --- a/books/embedded-rust-book/src/embedded-hal/traits.md +++ /dev/null @@ -1,12 +0,0 @@ -# Embedded-HAL Traits - -> **This section should cover:** -> -> * What are the embedded HAL traits used for? -> * Who writes them, and how? -> * How do they help us write more portable code? -> * What are some common traits? -> * A demo of our blinky demo using Embedded HAL traits -> * A demo of our application code, but running on an embedded linux GPIO impl instead? -> * Maybe a note on how even with this layer of abstraction, LLVM still "flattens" this code -> * Maybe a note that even if this isn't 100% most efficient in all cases, it is a good starting point until optimization is necessary \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/a-little-c.md b/books/embedded-rust-book/src/interop/a-little-c.md deleted file mode 100644 index c3657424..00000000 --- a/books/embedded-rust-book/src/interop/a-little-c.md +++ /dev/null @@ -1,16 +0,0 @@ -# A little C with your Rust - -> **This section should cover:** -> -> * How to take an existing component in C, and get it working from a Rust Main -> * How to manually write bindings -> * How to use `bindgen` to generate bindings -> * How to use `build.rs` build scripts -> * How to use `gcc-rs` to compile the other code (into a `.a` static archive) -> * How to go from a basic `Makefile` to a `build.rs` - -> **This section should steal from:** -> -> * https://docs.google.com/presentation/d/16oLlXMeBtvhW53oUfb8Iov4r2vxVbqT0Zbi9NL9zl7U/edit -> * Especially slides 15-29, 40-47 -> \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/a-little-rust.md b/books/embedded-rust-book/src/interop/a-little-rust.md deleted file mode 100644 index e6f6bfd0..00000000 --- a/books/embedded-rust-book/src/interop/a-little-rust.md +++ /dev/null @@ -1,8 +0,0 @@ -# A little Rust with your C - -> **This section should cover:** -> -> * How to make a `.a` static archive from a rust lib -> * How to manually write a `.h` header to be used by C code -> * How to generate a `.h` header automatically using `rusty-cheddar` or similar? -> * How to use `cargo` from a `Makefile` \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/build-with-cargo.md b/books/embedded-rust-book/src/interop/build-with-cargo.md deleted file mode 100644 index b56cc537..00000000 --- a/books/embedded-rust-book/src/interop/build-with-cargo.md +++ /dev/null @@ -1,5 +0,0 @@ -# Using Cargo as the primary build system - -> **This section should cover:** -> -> * More complex building, with Rust as the `main` \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/build-with-not-cargo.md b/books/embedded-rust-book/src/interop/build-with-not-cargo.md deleted file mode 100644 index f8e30ff9..00000000 --- a/books/embedded-rust-book/src/interop/build-with-not-cargo.md +++ /dev/null @@ -1,7 +0,0 @@ -# Using Cargo as a secondary build system - - -> **This section should cover:** -> -> * More complex build processes where Rust is not the main -> * Integrating with more than `Makefile`s? IAR? Eclipse? \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/freertos.md b/books/embedded-rust-book/src/interop/freertos.md deleted file mode 100644 index e215b63c..00000000 --- a/books/embedded-rust-book/src/interop/freertos.md +++ /dev/null @@ -1,7 +0,0 @@ -# Integrating with FreeRTOS - -> **This section should cover:** -> -> * How to use a Rust library as part of a larger FreeRTOS project -> * How to write a whole task in Rust -> * Use something like https://github.com/hashmismatch/freertos.rs \ No newline at end of file diff --git a/books/embedded-rust-book/src/interop/interop.md b/books/embedded-rust-book/src/interop/interop.md deleted file mode 100644 index 488608e8..00000000 --- a/books/embedded-rust-book/src/interop/interop.md +++ /dev/null @@ -1,11 +0,0 @@ -# Interoperability with existing codebases - -> **This section should cover:** -> -> * Reminder on how Rust has no runtime, etc, and plays nice with other systems languages -> * Practical examples of integrating Rust and other languages in both directions, including techniques for integration -> * WHY you would want to replace certain parts with Rust -> * Parsers, critical components -> * WHY you would want to NOT replace certain parts with Rust -> * Large, complex, and stable components, like drivers, network stacks, internal libraries -> * Tooling necessary for integration \ No newline at end of file diff --git a/books/embedded-rust-book/src/interoperability/c-with-rust.md b/books/embedded-rust-book/src/interoperability/c-with-rust.md new file mode 100644 index 00000000..17bd248e --- /dev/null +++ b/books/embedded-rust-book/src/interoperability/c-with-rust.md @@ -0,0 +1 @@ +# A little C with your Rust diff --git a/books/embedded-rust-book/src/interoperability/interoperability.md b/books/embedded-rust-book/src/interoperability/interoperability.md new file mode 100644 index 00000000..6b361113 --- /dev/null +++ b/books/embedded-rust-book/src/interoperability/interoperability.md @@ -0,0 +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. \ No newline at end of file diff --git a/books/embedded-rust-book/src/interoperability/rust-with-c.md b/books/embedded-rust-book/src/interoperability/rust-with-c.md new file mode 100644 index 00000000..9e56c0ca --- /dev/null +++ b/books/embedded-rust-book/src/interoperability/rust-with-c.md @@ -0,0 +1 @@ +# A little Rust with your C diff --git a/books/embedded-rust-book/src/intro/hardware.md b/books/embedded-rust-book/src/intro/hardware.md index e35e2676..d2afac62 100644 --- a/books/embedded-rust-book/src/intro/hardware.md +++ b/books/embedded-rust-book/src/intro/hardware.md @@ -1,9 +1,52 @@ -# Hardware - -> **This section should cover:** +> **⚠️: This section contains exports from [Japaric's Discovery] book.** > -> * Meet the hardware +> 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") + +

+ +

+ +We'll refer to this board as "F3" throughout this book. + +What does this board contain? + +- A STM32F303VCT6 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". + + - **IMPORTANT** This microcontroller operates at (around) 3.3V. + +- An [accelerometer] and a [magnetometer][] (in a single package). + +[accelerometer]: https://en.wikipedia.org/wiki/Accelerometer +[magnetometer]: https://en.wikipedia.org/wiki/Magnetometer + +- A [gyroscope]. + +[gyroscope]: https://en.wikipedia.org/wiki/Gyroscope + +- 8 user LEDs arranged in the shape of a compass + +- 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". + +- There's a second USB port, labeled "USB USER" that is connected to the main microcontroller, the + STM32F303VCT6, and can be used in applications. -> **This section should steal:** -> -> * https://japaric.github.io/discovery/04-meet-your-hardware/README.html \ No newline at end of file diff --git a/books/embedded-rust-book/src/intro/install.md b/books/embedded-rust-book/src/intro/install.md index 20fcc3f8..0fc03da4 100644 --- a/books/embedded-rust-book/src/intro/install.md +++ b/books/embedded-rust-book/src/intro/install.md @@ -1,14 +1,94 @@ -# Installation +> **⚠️: 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 should cover:** +> **⚠️: This section still references `nightly` Rust** > -> * Installing Rust, including a specific nightly version -> * Installing any additional deps, like `arm-none-eabi-gcc` -> * Installing any tools needed, like `openocd` -> * Installing any drivers necessary at the OS level -> * Installing `xargo` (for now)... -> * Doing all of the above for Windows, Mac, and Linux - -> **This section should steal:** +> Contents should be updated to work on `stable` Rust when possible + +> **⚠️: This section has not been checked as of 2018-07-29** > -> * https://japaric.github.io/discovery/03-setup/README.html \ No newline at end of file +> Contents should be checked to still be working with current `nightly` +> or `stable` Rust + +# 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. + +## Documentation + +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: + +*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] + +[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 +- 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 + +Next, follow OS-agnostic installation instructions for a few of the tools: + +### `rustc` & Cargo + +Install rustup by following the instructions at [https://rustup.rs](https://rustup.rs). + +Then, install or switch to the nightly channel. + +``` console +$ rustup default nightly +``` + +**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: + +``` console +$ rustc -V +rustc 1.28.0-nightly (29f48ccf3 2018-06-03) +``` + +### `itmdump` + +``` console +$ cargo install itm --vers 0.2.1 +``` + +### OS specific instructions + +Now follow the instructions specific to the OS you are using: + +- [Linux](intro/install/linux.html) +- [Windows](intro/install/windows.html) +- [macOS](intro/install/macos.html) diff --git a/books/embedded-rust-book/src/intro/install/linux.md b/books/embedded-rust-book/src/intro/install/linux.md new file mode 100644 index 00000000..5fef282e --- /dev/null +++ b/books/embedded-rust-book/src/intro/install/linux.md @@ -0,0 +1,130 @@ +> **⚠️: 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 + +# Linux + +Here are the installation commands for a few Linux distributions. + +## REQUIRED packages + +- Ubuntu 16.04 or newer / Debian Jessie or newer + +``` console +$ sudo apt-get install \ + binutils-arm-none-eabi \ + gdb-arm-none-eabi \ + minicom \ + openocd +``` + +- Fedora 23 or newer + +``` console +$ sudo dnf install \ + arm-none-eabi-gcc-cs \ + arm-none-eabi-gdb \ + minicom \ + openocd +``` + +- Arch Linux + +``` console +$ sudo pacman -S \ + arm-none-eabi-gcc \ + arm-none-eabi-gdb \ + arm-none-eabi-gcc \ + minicom + +$ yaourt -S openocd +``` + +## udev rules + +These rules let you use USB devices like the F3 and the Serial module without root privilege, i.e. +`sudo`. + +Create these two files 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 +``` + +``` text +# STM32F3DISCOVERY rev A/B - ST-LINK/V2 +ATTRS{idVendor}=="0483", ATTRS{idProduct}=="3748", GROUP="uucp" + +# STM32F3DISCOVERY rev C+ - ST-LINK/V2-1 +ATTRS{idVendor}=="0483", ATTRS{idProduct}=="374b", GROUP="uucp" +``` + +Then reload 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 + +- Add yourself to the `uucp` group. + +``` console +$ sudo usermod -a -G uucp $(id -u -n) +``` + +- Check again the output of `groups`. `uucp` should be there this time! + +``` console +$ groups $(id -nu) +(..) uucp (..) +$ # ^^^^ +``` + +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. + +Now, go to the [next section]. diff --git a/books/embedded-rust-book/src/intro/install/macos.md b/books/embedded-rust-book/src/intro/install/macos.md new file mode 100644 index 00000000..eae1456f --- /dev/null +++ b/books/embedded-rust-book/src/intro/install/macos.md @@ -0,0 +1,29 @@ +> **⚠️: 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 + +# MacOS + +All the tools can be install using [Homebrew]: + +[Homebrew]: http://brew.sh/ + +``` console +$ brew cask install gcc-arm-embedded +$ brew install minicom openocd +``` + +If the `brew cask` command doesn't work (`Error: Unknown command: cask`), then run `brew tap +Caskroom/tap` first and try again. + +That's all! Go to the [next section]. + +[next section]: 03-setup/verify.html diff --git a/books/embedded-rust-book/src/intro/install/verify.md b/books/embedded-rust-book/src/intro/install/verify.md new file mode 100644 index 00000000..b1d090a0 --- /dev/null +++ b/books/embedded-rust-book/src/intro/install/verify.md @@ -0,0 +1 @@ +# Verify Installation diff --git a/books/embedded-rust-book/src/intro/install/windows.md b/books/embedded-rust-book/src/intro/install/windows.md new file mode 100644 index 00000000..3a42f22c --- /dev/null +++ b/books/embedded-rust-book/src/intro/install/windows.md @@ -0,0 +1,62 @@ +> **⚠️: 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 + +# Windows + +## `arm-none-eabi-*` + +ARM provides `.exe` installers for Windows. Grab one from [here][gcc], and follow the instructions. +Just before the installation process finishes tick/select the "Add path to environment variable" +option. Then verify that the tools are in your `%PATH%`: + +``` console +$ arm-none-eabi-gcc -v +(..) +gcc version 5.4.1 20160919 (release) (..) +``` + +[gcc]: https://developer.arm.com/open-source/gnu-toolchain/gnu-rm/downloads + +## OpenOCD + +There's no official binary release of OpenOCD for Windows but there are unofficial releases +available [here][openocd]. Grab the 0.10.x zipfile and extract it somewhere in your drive (I +recommend `C:\OpenOCD` but with the drive letter that makes sense to you) then update your `%PATH%` +environment variable to include the following path: `C:\OpenOCD\bin` (or the path that you used +before). + +[openocd]: https://github.com/gnu-mcu-eclipse/openocd/releases + +Verify that OpenOCD is in yout `%PATH%` with: + +``` console +$ openocd -v +Open On-Chip Debugger 0.10.0 +(..) +``` + +## PuTTY + +Download the latest `putty.exe` from [this site] and place it somewhere in your `%PATH%`. + +[this site]: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html + +## ST-LINK USB driver + +You'll also need to install [this USB driver] or OpenOCD won't work. Follow the installer +instructions and make sure you install the right (32-bit or 64-bit) version of the driver. + +[this USB driver]: http://www.st.com/en/embedded-software/stsw-link009.html + +That's all! Go to the [next section]. + +[next section]: intro/install/verify.html diff --git a/books/embedded-rust-book/src/intro/no-std.md b/books/embedded-rust-book/src/intro/no-std.md new file mode 100644 index 00000000..8a737ecf --- /dev/null +++ b/books/embedded-rust-book/src/intro/no-std.md @@ -0,0 +1,5 @@ +# A `no_std` Rust Environment + +> ❌: **This section should cover:** +> +> * what #[no_std] means: no I/O (filesystems), allocation, etc. \ No newline at end of file diff --git a/books/embedded-rust-book/src/intro/preconditions.md b/books/embedded-rust-book/src/intro/preconditions.md deleted file mode 100644 index f940fa1c..00000000 --- a/books/embedded-rust-book/src/intro/preconditions.md +++ /dev/null @@ -1,7 +0,0 @@ -# Preconditions - -`TODO`. - -Is there anything to go here that is not covered by [the intro](./intro/introduction.html), under [Who This Book is For](./intro/introduction.html#who-this-book-is-for)? - -Maybe buying the board? diff --git a/books/embedded-rust-book/src/intro/tooling.md b/books/embedded-rust-book/src/intro/tooling.md index ed70eabc..71e7a6e5 100644 --- a/books/embedded-rust-book/src/intro/tooling.md +++ b/books/embedded-rust-book/src/intro/tooling.md @@ -1,5 +1,38 @@ # Tooling -> **This section should cover:** +> ❌: **This section should cover:** > -> * Basically explaining all the tools we installed in the previous chapter, what they are used for, etc. \ No newline at end of file +> * Basically explaining all the tools we installed in the previous chapter, what they are used for, etc. + +## rustc + +What is this, what is it used for, and why are we using this tool? + +## Cargo + +What is this, what is it used for, and why are we using this tool? + +## itmdump + +What is this, what is it used for, and why are we using this tool? + +## OpenOCD + +What is this, what is it used for, and why are we using this tool? + +## arm-none-eabi-gcc + +What is this, what is it used for, and why are we using this tool? + +## arm-none-eabi-ld + +What is this, what is it used for, and why are we using this tool? + +## arm-none-eabi-gdb + +What is this, what is it used for, and why are we using this tool? + +## minicom / putty + +What is this, what is it used for, and why are we using this tool? + diff --git a/books/embedded-rust-book/src/portability/portability.md b/books/embedded-rust-book/src/portability/portability.md new file mode 100644 index 00000000..bc2e2732 --- /dev/null +++ b/books/embedded-rust-book/src/portability/portability.md @@ -0,0 +1,3 @@ +# Portability + +> ❌: This section has not yet been written. Please refer to [embedded-wg#119](https://github.com/rust-lang-nursery/embedded-wg/issues/119) for discussion of this section. \ No newline at end of file diff --git a/books/embedded-rust-book/src/singletons/singletons.md b/books/embedded-rust-book/src/singletons/singletons.md new file mode 100644 index 00000000..8c08d3a7 --- /dev/null +++ b/books/embedded-rust-book/src/singletons/singletons.md @@ -0,0 +1,5 @@ +# Singletons + +> I see quite a bit of overlap between singletons and the "static guarantess" and "dynamic data structures" sections. It may be best to write those two first and the decide whether we want a standalone section on singletons (I think a standalone section would end up being too short and / or may not properly showcase its usefulness without applying it to something like configuration or memory management). +> +> - @japaric \ No newline at end of file diff --git a/books/embedded-rust-book/src/static-guarantees/static-guarantees.md b/books/embedded-rust-book/src/static-guarantees/static-guarantees.md new file mode 100644 index 00000000..df1e8110 --- /dev/null +++ b/books/embedded-rust-book/src/static-guarantees/static-guarantees.md @@ -0,0 +1,3 @@ +# Static Guarantees + +> ❌: This section has not yet been written. Please refer to [embedded-wg#817](https://github.com/rust-lang-nursery/embedded-wg/issues/118) for discussion of this section. \ No newline at end of file diff --git a/books/embedded-rust-book/src/testing/testing.md b/books/embedded-rust-book/src/testing/testing.md deleted file mode 100644 index 24c5a867..00000000 --- a/books/embedded-rust-book/src/testing/testing.md +++ /dev/null @@ -1,12 +0,0 @@ -# Testing your embedded project - -> **This section should cover:** -> -> * Organize your crate to be able to unit test logic on your host PC -> * Run tests with QEMU? -> * Run tests on-target? -> * Custom test runners? - -> **This section should steal:** -> -> * https://jamesmunns.com/update/2017/05/07/hardware-ci-overview.html \ No newline at end of file diff --git a/books/embedded-rust-book/src/tock/tock-os.md b/books/embedded-rust-book/src/tock/tock-os.md deleted file mode 100644 index 2dc7dcdd..00000000 --- a/books/embedded-rust-book/src/tock/tock-os.md +++ /dev/null @@ -1,8 +0,0 @@ -# The Tock-OS Ecosystem - -> **This section should cover:** -> -> * Shout out to Tock-OS -> * What kind of design choices are made in Tock-OS? -> * How to share code between embedded-hal and tock-os ecosystems -> * Mention any other ecosystems? diff --git a/books/embedded-rust-book/src/unsorted/abstractions.md b/books/embedded-rust-book/src/unsorted/abstractions.md deleted file mode 100644 index 7bf1be9b..00000000 --- a/books/embedded-rust-book/src/unsorted/abstractions.md +++ /dev/null @@ -1,9 +0,0 @@ -# Embracing Abstractions - -This section should illustrate that just because something "looks more complex" in the code, does NOT mean it makes inefficient or bloaty code. - -> **This section should cover:** -> -> * Using Generics (monomorphization) -> * Using things like Iterators (that flatten to loops when used as such) -> * ? \ No newline at end of file diff --git a/books/embedded-rust-book/src/unsorted/embedded-linux.md b/books/embedded-rust-book/src/unsorted/embedded-linux.md deleted file mode 100644 index c23dc93c..00000000 --- a/books/embedded-rust-book/src/unsorted/embedded-linux.md +++ /dev/null @@ -1,9 +0,0 @@ -# Embedded Linux - -This section should discuss how embedded linux is different than bare metal rust. - -Some stuff we might want to cover at some point: - -* Using tricks that are necessary in embedded to improve embedded linux -* Reducing binary size -* Sharing code with embedded-hal drivers \ No newline at end of file diff --git a/books/embedded-rust-book/src/unsorted/glossary.md b/books/embedded-rust-book/src/unsorted/glossary.md deleted file mode 100644 index 2434e23c..00000000 --- a/books/embedded-rust-book/src/unsorted/glossary.md +++ /dev/null @@ -1,3 +0,0 @@ -# Glossary - -We should have a list of all technical terms that are used in this guide. Each item should be some kind of header item, so we can permalink back to this page with anchors. \ No newline at end of file diff --git a/books/embedded-rust-book/src/unsorted/unknown.md b/books/embedded-rust-book/src/unsorted/unknown.md deleted file mode 100644 index 0301f73d..00000000 --- a/books/embedded-rust-book/src/unsorted/unknown.md +++ /dev/null @@ -1,9 +0,0 @@ -# Things we don't know how to do yet - -We should be upfront with the ugly side of the ecosystem. Hopefully it will inspire new ideas of how to fix them - -> **This section should cover:** -> -> * Interrupts, especially in a driver context -> * Sharing peripherals between drivers -> * ? \ No newline at end of file diff --git a/books/embedded-rust-book/src/unsorted/unlearning.md b/books/embedded-rust-book/src/unsorted/unlearning.md deleted file mode 100644 index 532b16a7..00000000 --- a/books/embedded-rust-book/src/unsorted/unlearning.md +++ /dev/null @@ -1,12 +0,0 @@ -# Unlearning Bad Embedded Habits - -I'm not sure about this section. I wanted to illustrate things that are considered "bad practice" in most places, but are widely used in Embedded still. Anything in this section should not focus on demeaning other techniques, but instead provide useful alternatives and recipes. - -If we can't come up with a positive way to spin this, we should remove this section. - -> **This section should cover:** -> -> * Global mutable state, including peripherals -> * Code reuse -> * Premature optimization -> * Raw pointer indexing diff --git a/books/embedded-rust-book/src/unsorted/unsafe.md b/books/embedded-rust-book/src/unsorted/unsafe.md deleted file mode 100644 index 1191e7b7..00000000 --- a/books/embedded-rust-book/src/unsorted/unsafe.md +++ /dev/null @@ -1,5 +0,0 @@ -# Proper use of unsafe - -> **This section should cover:** -> -> * Singletons, ownership, and the type system - "Make your assumptions machine checkable" diff --git a/books/embedded-rust-book/src/unsorted/unsorted.md b/books/embedded-rust-book/src/unsorted/unsorted.md deleted file mode 100644 index 694f0b7a..00000000 --- a/books/embedded-rust-book/src/unsorted/unsorted.md +++ /dev/null @@ -1,3 +0,0 @@ -# Unsorted - -I didn't know where to put this stuff, but it should probably be rolled in somewhere... \ No newline at end of file