Initial Embedded Book Skeleton

embedded-rust-book/.gitignore

@@ -0,0 +1 @@
+book

embedded-rust-book/README.md

@@ -0,0 +1,19 @@
+# [Work in Progress] - The Embedded Rust Book
+
+See [this issue] for more details. This is a very early work in progress.
+
+[this issue]: https://github.com/rust-lang-nursery/embedded-wg/issues/56
+
+## Using
+
+```
+cargo install mdbook
+cd embedded-rust-book
+mdbook serve
+
+# open a web browser, go to http://localhost:3001
+```
+
+## License
+
+Not yet determined. Likely Apache/MIT, maybe something CC.

embedded-rust-book/book.toml

@@ -0,0 +1,5 @@
+[book]
+authors = ["James Munns"]
+multilingual = false
+src = "src"
+title = "The Embedded Rust Book"

embedded-rust-book/src/SUMMARY.md

@@ -0,0 +1,38 @@
+# Summary
+
+- [Introduction](./intro/introduction.md)
+    - [Preconditions](./intro/preconditions.md)
+    - [Installation](./intro/install.md)
+    - [Tooling](./intro/tooling.md)
+    - [Hardware](./intro/hardware.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)

embedded-rust-book/src/blinky/blinky.md

@@ -0,0 +1,7 @@
+# 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

embedded-rust-book/src/blinky/compiling.md

@@ -0,0 +1,6 @@
+# Compiling
+
+> **This section should cover:**
+>
+> * How to compile
+> * Whatever errors are produced because we dont have a linker script (yet)

embedded-rust-book/src/blinky/linking.md

@@ -0,0 +1,6 @@
+# Linking
+
+> **This section should cover:**
+>
+> * Adding a linker script to the project
+> * Informing Cargo about the linker script

embedded-rust-book/src/blinky/run-and-debug.md

@@ -0,0 +1,7 @@
+# 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

embedded-rust-book/src/blinky/setup.md

@@ -0,0 +1,8 @@
+# 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

embedded-rust-book/src/blinky/writing.md

@@ -0,0 +1,7 @@
+# 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

embedded-rust-book/src/embedded-hal/application.md

@@ -0,0 +1,12 @@
+# 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?

embedded-rust-book/src/embedded-hal/bsp.md

@@ -0,0 +1,8 @@
+# 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

embedded-rust-book/src/embedded-hal/changing-targets.md

@@ -0,0 +1,7 @@
+# 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

embedded-rust-book/src/embedded-hal/csp.md

@@ -0,0 +1,9 @@
+# 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

embedded-rust-book/src/embedded-hal/drivers.md

@@ -0,0 +1,7 @@
+# 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?

embedded-rust-book/src/embedded-hal/embedded-hal.md

@@ -0,0 +1,9 @@
+# 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

embedded-rust-book/src/embedded-hal/rdc.md

@@ -0,0 +1,10 @@
+# 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

embedded-rust-book/src/embedded-hal/rtfm.md

@@ -0,0 +1,8 @@
+# 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)

embedded-rust-book/src/embedded-hal/traits.md

@@ -0,0 +1,12 @@
+# 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

embedded-rust-book/src/interop/a-little-c.md

@@ -0,0 +1,16 @@
+# 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
+>

embedded-rust-book/src/interop/a-little-rust.md

@@ -0,0 +1,8 @@
+# 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`

embedded-rust-book/src/interop/build-with-cargo.md

@@ -0,0 +1,5 @@
+# Using Cargo as the primary build system
+
+> **This section should cover:**
+>
+> * More complex building, with Rust as the `main`

embedded-rust-book/src/interop/build-with-not-cargo.md

@@ -0,0 +1,7 @@
+# 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?

embedded-rust-book/src/interop/freertos.md

@@ -0,0 +1,7 @@
+# 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

embedded-rust-book/src/interop/interop.md

@@ -0,0 +1,11 @@
+# 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

embedded-rust-book/src/intro/hardware.md

@@ -0,0 +1,9 @@
+# Hardware
+
+> **This section should cover:**
+>
+> * Meet the hardware
+
+> **This section should steal:**
+>
+> * https://japaric.github.io/discovery/04-meet-your-hardware/README.html

embedded-rust-book/src/intro/install.md

@@ -0,0 +1,14 @@
+# Installation
+
+> **This section should cover:**
+>
+> * 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:**
+>
+> * https://japaric.github.io/discovery/03-setup/README.html

embedded-rust-book/src/intro/introduction.md

@@ -0,0 +1,42 @@
+# Introduction
+
+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
+
+`TODO`
+
+## Who This Book is For
+
+This book assumes the following:
+
+* You are comfortable using the Rust Programming Language, and have written, run, and debugged Rust applications on a desktop environment
+* You are comfortable developing and debugging embedded systems in another language such as C, C++, or ADA, and are familiar with concepts such as:
+    * Cross Compilation
+    * Linker Scripts
+    * Memory Mapped Peripherals
+    * Interrupts
+    * Common interfaces such as I2C, SPI, Serial, and others
+
+If you are not yet comfortable with Rust, we highly suggest completing the [Rust Book] before attempting to learn with this book.
+
+If you are not yet comfortable with Embedded Systems, we highly suggest `LEARNING WITH OTHER RESOURCES` before attempting to learn with this book.
+
+[Rust Book]: https://doc.rust-lang.org/book/second-edition
+
+## How to Use This Book
+
+This book generally assumes that you’re reading it front-to-back, that is, later chapters build on top of concepts in earlier chapters, and earlier chapters may not dig into details on a topic, revisiting the topic in a later chapter.
+
+This book will be using the `UNDEFINED` development board from `UNDEFINED` 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 implementation details of Microcontrollers are different between different vendors, and often even different between Microcontroller families from the same vendor.
+
+For this reason, we suggest purchasing the `UNDEFINED` development board for the purpose of following this book.
+
+## Contributing to This Book
+
+Until the initial release of this book (planned to coincide with the 2018 Era release of the Rust Programming Language), the work on this book will be coordinated in [this tracking issue] of the [Embedded Working Group] repository.
+
+Pull requests are very welcome.
+
+[this tracking issue]: https://github.com/rust-lang-nursery/embedded-wg/issues/56
+[Embedded Working Group]: https://github.com/rust-lang-nursery/embedded-wg

embedded-rust-book/src/intro/preconditions.md

@@ -0,0 +1,7 @@
+# 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?

embedded-rust-book/src/intro/tooling.md

@@ -0,0 +1,5 @@
+# Tooling
+
+> **This section should cover:**
+>
+> * Basically explaining all the tools we installed in the previous chapter, what they are used for, etc.

embedded-rust-book/src/testing/testing.md

@@ -0,0 +1,12 @@
+# 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

embedded-rust-book/src/tock/tock-os.md

@@ -0,0 +1,8 @@
+# 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?