From 808e03675d8d6bbe062fd214aec94a1861ef5f73 Mon Sep 17 00:00:00 2001 From: James Munns Date: Thu, 29 Mar 2018 19:07:55 +0200 Subject: [PATCH 1/5] Initial blank skeleton of the book --- embedded-rust-book/.gitignore | 1 + embedded-rust-book/book.toml | 5 +++ embedded-rust-book/src/SUMMARY.md | 35 +++++++++++++++++++ embedded-rust-book/src/blinky/blinky.md | 1 + embedded-rust-book/src/blinky/compiling.md | 1 + embedded-rust-book/src/blinky/linking.md | 1 + .../src/blinky/run-and-debug.md | 1 + embedded-rust-book/src/blinky/setup.md | 1 + embedded-rust-book/src/blinky/writing.md | 1 + .../src/embedded-hal/application.md | 1 + embedded-rust-book/src/embedded-hal/bsp.md | 1 + .../src/embedded-hal/changing-targets.md | 1 + embedded-rust-book/src/embedded-hal/csp.md | 1 + .../src/embedded-hal/drivers.md | 1 + .../src/embedded-hal/embedded-hal.md | 1 + embedded-rust-book/src/embedded-hal/rtfm.md | 1 + embedded-rust-book/src/embedded-hal/traits.md | 1 + embedded-rust-book/src/interop/a-little-c.md | 1 + .../src/interop/a-little-rust.md | 1 + .../src/interop/build-with-cargo.md | 1 + .../src/interop/build-with-not-cargo.md | 1 + embedded-rust-book/src/interop/freertos.md | 1 + embedded-rust-book/src/interop/interop.md | 1 + embedded-rust-book/src/intro/hardware.md | 1 + embedded-rust-book/src/intro/install.md | 1 + embedded-rust-book/src/intro/introduction.md | 1 + embedded-rust-book/src/intro/preconditions.md | 1 + embedded-rust-book/src/intro/tooling.md | 1 + embedded-rust-book/src/testing/testing.md | 1 + embedded-rust-book/src/tock/tock-os.md | 1 + .../src/unsorted/abstractions.md | 1 + .../src/unsorted/embedded-linux.md | 1 + embedded-rust-book/src/unsorted/unlearning.md | 1 + embedded-rust-book/src/unsorted/unsafe.md | 1 + embedded-rust-book/src/unsorted/unsorted.md | 1 + 35 files changed, 73 insertions(+) create mode 100644 embedded-rust-book/.gitignore create mode 100644 embedded-rust-book/book.toml create mode 100644 embedded-rust-book/src/SUMMARY.md create mode 100644 embedded-rust-book/src/blinky/blinky.md create mode 100644 embedded-rust-book/src/blinky/compiling.md create mode 100644 embedded-rust-book/src/blinky/linking.md create mode 100644 embedded-rust-book/src/blinky/run-and-debug.md create mode 100644 embedded-rust-book/src/blinky/setup.md create mode 100644 embedded-rust-book/src/blinky/writing.md create mode 100644 embedded-rust-book/src/embedded-hal/application.md create mode 100644 embedded-rust-book/src/embedded-hal/bsp.md create mode 100644 embedded-rust-book/src/embedded-hal/changing-targets.md create mode 100644 embedded-rust-book/src/embedded-hal/csp.md create mode 100644 embedded-rust-book/src/embedded-hal/drivers.md create mode 100644 embedded-rust-book/src/embedded-hal/embedded-hal.md create mode 100644 embedded-rust-book/src/embedded-hal/rtfm.md create mode 100644 embedded-rust-book/src/embedded-hal/traits.md create mode 100644 embedded-rust-book/src/interop/a-little-c.md create mode 100644 embedded-rust-book/src/interop/a-little-rust.md create mode 100644 embedded-rust-book/src/interop/build-with-cargo.md create mode 100644 embedded-rust-book/src/interop/build-with-not-cargo.md create mode 100644 embedded-rust-book/src/interop/freertos.md create mode 100644 embedded-rust-book/src/interop/interop.md create mode 100644 embedded-rust-book/src/intro/hardware.md create mode 100644 embedded-rust-book/src/intro/install.md create mode 100644 embedded-rust-book/src/intro/introduction.md create mode 100644 embedded-rust-book/src/intro/preconditions.md create mode 100644 embedded-rust-book/src/intro/tooling.md create mode 100644 embedded-rust-book/src/testing/testing.md create mode 100644 embedded-rust-book/src/tock/tock-os.md create mode 100644 embedded-rust-book/src/unsorted/abstractions.md create mode 100644 embedded-rust-book/src/unsorted/embedded-linux.md create mode 100644 embedded-rust-book/src/unsorted/unlearning.md create mode 100644 embedded-rust-book/src/unsorted/unsafe.md create mode 100644 embedded-rust-book/src/unsorted/unsorted.md diff --git a/embedded-rust-book/.gitignore b/embedded-rust-book/.gitignore new file mode 100644 index 00000000..7585238e --- /dev/null +++ b/embedded-rust-book/.gitignore @@ -0,0 +1 @@ +book diff --git a/embedded-rust-book/book.toml b/embedded-rust-book/book.toml new file mode 100644 index 00000000..0db4ffa8 --- /dev/null +++ b/embedded-rust-book/book.toml @@ -0,0 +1,5 @@ +[book] +authors = ["James Munns"] +multilingual = false +src = "src" +title = "The Embedded Rust Book" diff --git a/embedded-rust-book/src/SUMMARY.md b/embedded-rust-book/src/SUMMARY.md new file mode 100644 index 00000000..735b4945 --- /dev/null +++ b/embedded-rust-book/src/SUMMARY.md @@ -0,0 +1,35 @@ +# 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) + - [Chip Support Crates](./embedded-hal/csp.md) + - [Board Support Crates](./embedded-hal/bsp.md) + - [`Embedded-HAL` Traits](./embedded-hal/traits.md) + - [Driver Crates](./embedded-hal/drivers.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) + - [Embedded Linux](./unsorted/embedded-linux.md) \ No newline at end of file diff --git a/embedded-rust-book/src/blinky/blinky.md b/embedded-rust-book/src/blinky/blinky.md new file mode 100644 index 00000000..adb4b298 --- /dev/null +++ b/embedded-rust-book/src/blinky/blinky.md @@ -0,0 +1 @@ +# Blinking your first LED diff --git a/embedded-rust-book/src/blinky/compiling.md b/embedded-rust-book/src/blinky/compiling.md new file mode 100644 index 00000000..6d6a98c4 --- /dev/null +++ b/embedded-rust-book/src/blinky/compiling.md @@ -0,0 +1 @@ +# Compiling diff --git a/embedded-rust-book/src/blinky/linking.md b/embedded-rust-book/src/blinky/linking.md new file mode 100644 index 00000000..7f9c799a --- /dev/null +++ b/embedded-rust-book/src/blinky/linking.md @@ -0,0 +1 @@ +# Linking diff --git a/embedded-rust-book/src/blinky/run-and-debug.md b/embedded-rust-book/src/blinky/run-and-debug.md new file mode 100644 index 00000000..766b9dbc --- /dev/null +++ b/embedded-rust-book/src/blinky/run-and-debug.md @@ -0,0 +1 @@ +# Running and Debugging diff --git a/embedded-rust-book/src/blinky/setup.md b/embedded-rust-book/src/blinky/setup.md new file mode 100644 index 00000000..c10650bb --- /dev/null +++ b/embedded-rust-book/src/blinky/setup.md @@ -0,0 +1 @@ +# Project Setup diff --git a/embedded-rust-book/src/blinky/writing.md b/embedded-rust-book/src/blinky/writing.md new file mode 100644 index 00000000..eb432df3 --- /dev/null +++ b/embedded-rust-book/src/blinky/writing.md @@ -0,0 +1 @@ +# Writing diff --git a/embedded-rust-book/src/embedded-hal/application.md b/embedded-rust-book/src/embedded-hal/application.md new file mode 100644 index 00000000..aedc5105 --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/application.md @@ -0,0 +1 @@ +# Your Application Code diff --git a/embedded-rust-book/src/embedded-hal/bsp.md b/embedded-rust-book/src/embedded-hal/bsp.md new file mode 100644 index 00000000..865027bd --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/bsp.md @@ -0,0 +1 @@ +# Board Support Crates diff --git a/embedded-rust-book/src/embedded-hal/changing-targets.md b/embedded-rust-book/src/embedded-hal/changing-targets.md new file mode 100644 index 00000000..a9f089e1 --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/changing-targets.md @@ -0,0 +1 @@ +# Changing Targets diff --git a/embedded-rust-book/src/embedded-hal/csp.md b/embedded-rust-book/src/embedded-hal/csp.md new file mode 100644 index 00000000..07788562 --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/csp.md @@ -0,0 +1 @@ +# Chip Support Crates diff --git a/embedded-rust-book/src/embedded-hal/drivers.md b/embedded-rust-book/src/embedded-hal/drivers.md new file mode 100644 index 00000000..f38b2cae --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/drivers.md @@ -0,0 +1 @@ +# Driver Crates diff --git a/embedded-rust-book/src/embedded-hal/embedded-hal.md b/embedded-rust-book/src/embedded-hal/embedded-hal.md new file mode 100644 index 00000000..415c047f --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/embedded-hal.md @@ -0,0 +1 @@ +# The Embedded-HAL Ecosystem diff --git a/embedded-rust-book/src/embedded-hal/rtfm.md b/embedded-rust-book/src/embedded-hal/rtfm.md new file mode 100644 index 00000000..9d6b4300 --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/rtfm.md @@ -0,0 +1 @@ +# RTFM: An Embedded-HAL based RTOS diff --git a/embedded-rust-book/src/embedded-hal/traits.md b/embedded-rust-book/src/embedded-hal/traits.md new file mode 100644 index 00000000..264d5ee0 --- /dev/null +++ b/embedded-rust-book/src/embedded-hal/traits.md @@ -0,0 +1 @@ +# Embedded-HAL Traits diff --git a/embedded-rust-book/src/interop/a-little-c.md b/embedded-rust-book/src/interop/a-little-c.md new file mode 100644 index 00000000..17bd248e --- /dev/null +++ b/embedded-rust-book/src/interop/a-little-c.md @@ -0,0 +1 @@ +# A little C with your Rust diff --git a/embedded-rust-book/src/interop/a-little-rust.md b/embedded-rust-book/src/interop/a-little-rust.md new file mode 100644 index 00000000..9e56c0ca --- /dev/null +++ b/embedded-rust-book/src/interop/a-little-rust.md @@ -0,0 +1 @@ +# A little Rust with your C diff --git a/embedded-rust-book/src/interop/build-with-cargo.md b/embedded-rust-book/src/interop/build-with-cargo.md new file mode 100644 index 00000000..14cfc85d --- /dev/null +++ b/embedded-rust-book/src/interop/build-with-cargo.md @@ -0,0 +1 @@ +# Using Cargo as the primary build system diff --git a/embedded-rust-book/src/interop/build-with-not-cargo.md b/embedded-rust-book/src/interop/build-with-not-cargo.md new file mode 100644 index 00000000..a9826ae7 --- /dev/null +++ b/embedded-rust-book/src/interop/build-with-not-cargo.md @@ -0,0 +1 @@ +# Using Cargo as a secondary build system diff --git a/embedded-rust-book/src/interop/freertos.md b/embedded-rust-book/src/interop/freertos.md new file mode 100644 index 00000000..02a6338d --- /dev/null +++ b/embedded-rust-book/src/interop/freertos.md @@ -0,0 +1 @@ +# Integrating with FreeRTOS diff --git a/embedded-rust-book/src/interop/interop.md b/embedded-rust-book/src/interop/interop.md new file mode 100644 index 00000000..54d0536d --- /dev/null +++ b/embedded-rust-book/src/interop/interop.md @@ -0,0 +1 @@ +# Interoperability with existing codebases diff --git a/embedded-rust-book/src/intro/hardware.md b/embedded-rust-book/src/intro/hardware.md new file mode 100644 index 00000000..33c0dddc --- /dev/null +++ b/embedded-rust-book/src/intro/hardware.md @@ -0,0 +1 @@ +# Hardware diff --git a/embedded-rust-book/src/intro/install.md b/embedded-rust-book/src/intro/install.md new file mode 100644 index 00000000..25267fe2 --- /dev/null +++ b/embedded-rust-book/src/intro/install.md @@ -0,0 +1 @@ +# Installation diff --git a/embedded-rust-book/src/intro/introduction.md b/embedded-rust-book/src/intro/introduction.md new file mode 100644 index 00000000..e10b99d0 --- /dev/null +++ b/embedded-rust-book/src/intro/introduction.md @@ -0,0 +1 @@ +# Introduction diff --git a/embedded-rust-book/src/intro/preconditions.md b/embedded-rust-book/src/intro/preconditions.md new file mode 100644 index 00000000..8df6fd30 --- /dev/null +++ b/embedded-rust-book/src/intro/preconditions.md @@ -0,0 +1 @@ +# Preconditions diff --git a/embedded-rust-book/src/intro/tooling.md b/embedded-rust-book/src/intro/tooling.md new file mode 100644 index 00000000..a07e7c8b --- /dev/null +++ b/embedded-rust-book/src/intro/tooling.md @@ -0,0 +1 @@ +# Tooling diff --git a/embedded-rust-book/src/testing/testing.md b/embedded-rust-book/src/testing/testing.md new file mode 100644 index 00000000..6b6b47ce --- /dev/null +++ b/embedded-rust-book/src/testing/testing.md @@ -0,0 +1 @@ +# Testing your embedded project diff --git a/embedded-rust-book/src/tock/tock-os.md b/embedded-rust-book/src/tock/tock-os.md new file mode 100644 index 00000000..3a94daf5 --- /dev/null +++ b/embedded-rust-book/src/tock/tock-os.md @@ -0,0 +1 @@ +# The Tock-OS Ecosystem diff --git a/embedded-rust-book/src/unsorted/abstractions.md b/embedded-rust-book/src/unsorted/abstractions.md new file mode 100644 index 00000000..6adbb468 --- /dev/null +++ b/embedded-rust-book/src/unsorted/abstractions.md @@ -0,0 +1 @@ +# Embracing Abstractions diff --git a/embedded-rust-book/src/unsorted/embedded-linux.md b/embedded-rust-book/src/unsorted/embedded-linux.md new file mode 100644 index 00000000..5cb1aca3 --- /dev/null +++ b/embedded-rust-book/src/unsorted/embedded-linux.md @@ -0,0 +1 @@ +# Embedded Linux diff --git a/embedded-rust-book/src/unsorted/unlearning.md b/embedded-rust-book/src/unsorted/unlearning.md new file mode 100644 index 00000000..f3d5e734 --- /dev/null +++ b/embedded-rust-book/src/unsorted/unlearning.md @@ -0,0 +1 @@ +# Unlearning Bad Embedded Habits diff --git a/embedded-rust-book/src/unsorted/unsafe.md b/embedded-rust-book/src/unsorted/unsafe.md new file mode 100644 index 00000000..cbf2b761 --- /dev/null +++ b/embedded-rust-book/src/unsorted/unsafe.md @@ -0,0 +1 @@ +# Proper use of unsafe diff --git a/embedded-rust-book/src/unsorted/unsorted.md b/embedded-rust-book/src/unsorted/unsorted.md new file mode 100644 index 00000000..d972012f --- /dev/null +++ b/embedded-rust-book/src/unsorted/unsorted.md @@ -0,0 +1 @@ +# Unsorted From 1b8527dee2541973bdcfcd71bc38a97657b29484 Mon Sep 17 00:00:00 2001 From: James Munns Date: Thu, 29 Mar 2018 21:02:06 +0200 Subject: [PATCH 2/5] Initial outline runthrough, added a couple sections --- embedded-rust-book/README.md | 19 +++++++++ embedded-rust-book/src/SUMMARY.md | 7 +++- embedded-rust-book/src/blinky/blinky.md | 6 +++ embedded-rust-book/src/blinky/compiling.md | 5 +++ embedded-rust-book/src/blinky/linking.md | 5 +++ .../src/blinky/run-and-debug.md | 6 +++ embedded-rust-book/src/blinky/setup.md | 7 ++++ embedded-rust-book/src/blinky/writing.md | 6 +++ .../src/embedded-hal/application.md | 11 +++++ embedded-rust-book/src/embedded-hal/bsp.md | 7 ++++ .../src/embedded-hal/changing-targets.md | 6 +++ embedded-rust-book/src/embedded-hal/csp.md | 8 ++++ .../src/embedded-hal/drivers.md | 6 +++ .../src/embedded-hal/embedded-hal.md | 8 ++++ embedded-rust-book/src/embedded-hal/rdc.md | 10 +++++ embedded-rust-book/src/embedded-hal/rtfm.md | 7 ++++ embedded-rust-book/src/embedded-hal/traits.md | 11 +++++ embedded-rust-book/src/interop/a-little-c.md | 15 +++++++ .../src/interop/a-little-rust.md | 7 ++++ .../src/interop/build-with-cargo.md | 4 ++ .../src/interop/build-with-not-cargo.md | 6 +++ embedded-rust-book/src/interop/freertos.md | 6 +++ embedded-rust-book/src/interop/interop.md | 10 +++++ embedded-rust-book/src/intro/hardware.md | 8 ++++ embedded-rust-book/src/intro/install.md | 13 ++++++ embedded-rust-book/src/intro/introduction.md | 41 +++++++++++++++++++ embedded-rust-book/src/intro/preconditions.md | 6 +++ embedded-rust-book/src/intro/tooling.md | 4 ++ embedded-rust-book/src/testing/testing.md | 11 +++++ embedded-rust-book/src/tock/tock-os.md | 7 ++++ .../src/unsorted/abstractions.md | 8 ++++ .../src/unsorted/embedded-linux.md | 8 ++++ embedded-rust-book/src/unsorted/glossary.md | 3 ++ embedded-rust-book/src/unsorted/unknown.md | 9 ++++ embedded-rust-book/src/unsorted/unlearning.md | 11 +++++ embedded-rust-book/src/unsorted/unsafe.md | 4 ++ embedded-rust-book/src/unsorted/unsorted.md | 2 + 37 files changed, 316 insertions(+), 2 deletions(-) create mode 100644 embedded-rust-book/README.md create mode 100644 embedded-rust-book/src/embedded-hal/rdc.md create mode 100644 embedded-rust-book/src/unsorted/glossary.md create mode 100644 embedded-rust-book/src/unsorted/unknown.md diff --git a/embedded-rust-book/README.md b/embedded-rust-book/README.md new file mode 100644 index 00000000..0fd2a148 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/embedded-rust-book/src/SUMMARY.md b/embedded-rust-book/src/SUMMARY.md index 735b4945..c3650eb5 100644 --- a/embedded-rust-book/src/SUMMARY.md +++ b/embedded-rust-book/src/SUMMARY.md @@ -12,10 +12,11 @@ - [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) - - [Board Support Crates](./embedded-hal/bsp.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) @@ -32,4 +33,6 @@ - [Embracing Abstractions](./unsorted/abstractions.md) - [Unlearning Bad Embedded Habits](./unsorted/unlearning.md) - [Proper use of `unsafe`](./unsorted/unsafe.md) - - [Embedded Linux](./unsorted/embedded-linux.md) \ No newline at end of file + - [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 diff --git a/embedded-rust-book/src/blinky/blinky.md b/embedded-rust-book/src/blinky/blinky.md index adb4b298..c3db278e 100644 --- a/embedded-rust-book/src/blinky/blinky.md +++ b/embedded-rust-book/src/blinky/blinky.md @@ -1 +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 diff --git a/embedded-rust-book/src/blinky/compiling.md b/embedded-rust-book/src/blinky/compiling.md index 6d6a98c4..16856e35 100644 --- a/embedded-rust-book/src/blinky/compiling.md +++ b/embedded-rust-book/src/blinky/compiling.md @@ -1 +1,6 @@ # 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/embedded-rust-book/src/blinky/linking.md b/embedded-rust-book/src/blinky/linking.md index 7f9c799a..81d2db93 100644 --- a/embedded-rust-book/src/blinky/linking.md +++ b/embedded-rust-book/src/blinky/linking.md @@ -1 +1,6 @@ # 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/embedded-rust-book/src/blinky/run-and-debug.md b/embedded-rust-book/src/blinky/run-and-debug.md index 766b9dbc..f5b853ea 100644 --- a/embedded-rust-book/src/blinky/run-and-debug.md +++ b/embedded-rust-book/src/blinky/run-and-debug.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/blinky/setup.md b/embedded-rust-book/src/blinky/setup.md index c10650bb..506c292a 100644 --- a/embedded-rust-book/src/blinky/setup.md +++ b/embedded-rust-book/src/blinky/setup.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/blinky/writing.md b/embedded-rust-book/src/blinky/writing.md index eb432df3..7467d676 100644 --- a/embedded-rust-book/src/blinky/writing.md +++ b/embedded-rust-book/src/blinky/writing.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/application.md b/embedded-rust-book/src/embedded-hal/application.md index aedc5105..7b712253 100644 --- a/embedded-rust-book/src/embedded-hal/application.md +++ b/embedded-rust-book/src/embedded-hal/application.md @@ -1 +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? \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/bsp.md b/embedded-rust-book/src/embedded-hal/bsp.md index 865027bd..e7726583 100644 --- a/embedded-rust-book/src/embedded-hal/bsp.md +++ b/embedded-rust-book/src/embedded-hal/bsp.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/changing-targets.md b/embedded-rust-book/src/embedded-hal/changing-targets.md index a9f089e1..8aecaffd 100644 --- a/embedded-rust-book/src/embedded-hal/changing-targets.md +++ b/embedded-rust-book/src/embedded-hal/changing-targets.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/csp.md b/embedded-rust-book/src/embedded-hal/csp.md index 07788562..dda228d1 100644 --- a/embedded-rust-book/src/embedded-hal/csp.md +++ b/embedded-rust-book/src/embedded-hal/csp.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/drivers.md b/embedded-rust-book/src/embedded-hal/drivers.md index f38b2cae..4e5330ef 100644 --- a/embedded-rust-book/src/embedded-hal/drivers.md +++ b/embedded-rust-book/src/embedded-hal/drivers.md @@ -1 +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? \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/embedded-hal.md b/embedded-rust-book/src/embedded-hal/embedded-hal.md index 415c047f..9dca81f7 100644 --- a/embedded-rust-book/src/embedded-hal/embedded-hal.md +++ b/embedded-rust-book/src/embedded-hal/embedded-hal.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/rdc.md b/embedded-rust-book/src/embedded-hal/rdc.md new file mode 100644 index 00000000..6a8a2838 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/rtfm.md b/embedded-rust-book/src/embedded-hal/rtfm.md index 9d6b4300..ce234ee9 100644 --- a/embedded-rust-book/src/embedded-hal/rtfm.md +++ b/embedded-rust-book/src/embedded-hal/rtfm.md @@ -1 +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) \ No newline at end of file diff --git a/embedded-rust-book/src/embedded-hal/traits.md b/embedded-rust-book/src/embedded-hal/traits.md index 264d5ee0..0f0b75c8 100644 --- a/embedded-rust-book/src/embedded-hal/traits.md +++ b/embedded-rust-book/src/embedded-hal/traits.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/interop/a-little-c.md b/embedded-rust-book/src/interop/a-little-c.md index 17bd248e..c3657424 100644 --- a/embedded-rust-book/src/interop/a-little-c.md +++ b/embedded-rust-book/src/interop/a-little-c.md @@ -1 +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 +> \ No newline at end of file diff --git a/embedded-rust-book/src/interop/a-little-rust.md b/embedded-rust-book/src/interop/a-little-rust.md index 9e56c0ca..e6f6bfd0 100644 --- a/embedded-rust-book/src/interop/a-little-rust.md +++ b/embedded-rust-book/src/interop/a-little-rust.md @@ -1 +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` \ No newline at end of file diff --git a/embedded-rust-book/src/interop/build-with-cargo.md b/embedded-rust-book/src/interop/build-with-cargo.md index 14cfc85d..b56cc537 100644 --- a/embedded-rust-book/src/interop/build-with-cargo.md +++ b/embedded-rust-book/src/interop/build-with-cargo.md @@ -1 +1,5 @@ # 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/embedded-rust-book/src/interop/build-with-not-cargo.md b/embedded-rust-book/src/interop/build-with-not-cargo.md index a9826ae7..f8e30ff9 100644 --- a/embedded-rust-book/src/interop/build-with-not-cargo.md +++ b/embedded-rust-book/src/interop/build-with-not-cargo.md @@ -1 +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? \ No newline at end of file diff --git a/embedded-rust-book/src/interop/freertos.md b/embedded-rust-book/src/interop/freertos.md index 02a6338d..e215b63c 100644 --- a/embedded-rust-book/src/interop/freertos.md +++ b/embedded-rust-book/src/interop/freertos.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/interop/interop.md b/embedded-rust-book/src/interop/interop.md index 54d0536d..488608e8 100644 --- a/embedded-rust-book/src/interop/interop.md +++ b/embedded-rust-book/src/interop/interop.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/intro/hardware.md b/embedded-rust-book/src/intro/hardware.md index 33c0dddc..e35e2676 100644 --- a/embedded-rust-book/src/intro/hardware.md +++ b/embedded-rust-book/src/intro/hardware.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/intro/install.md b/embedded-rust-book/src/intro/install.md index 25267fe2..20fcc3f8 100644 --- a/embedded-rust-book/src/intro/install.md +++ b/embedded-rust-book/src/intro/install.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/intro/introduction.md b/embedded-rust-book/src/intro/introduction.md index e10b99d0..4754f3fd 100644 --- a/embedded-rust-book/src/intro/introduction.md +++ b/embedded-rust-book/src/intro/introduction.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/intro/preconditions.md b/embedded-rust-book/src/intro/preconditions.md index 8df6fd30..f940fa1c 100644 --- a/embedded-rust-book/src/intro/preconditions.md +++ b/embedded-rust-book/src/intro/preconditions.md @@ -1 +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? diff --git a/embedded-rust-book/src/intro/tooling.md b/embedded-rust-book/src/intro/tooling.md index a07e7c8b..ed70eabc 100644 --- a/embedded-rust-book/src/intro/tooling.md +++ b/embedded-rust-book/src/intro/tooling.md @@ -1 +1,5 @@ # Tooling + +> **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 diff --git a/embedded-rust-book/src/testing/testing.md b/embedded-rust-book/src/testing/testing.md index 6b6b47ce..24c5a867 100644 --- a/embedded-rust-book/src/testing/testing.md +++ b/embedded-rust-book/src/testing/testing.md @@ -1 +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 \ No newline at end of file diff --git a/embedded-rust-book/src/tock/tock-os.md b/embedded-rust-book/src/tock/tock-os.md index 3a94daf5..2dc7dcdd 100644 --- a/embedded-rust-book/src/tock/tock-os.md +++ b/embedded-rust-book/src/tock/tock-os.md @@ -1 +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? diff --git a/embedded-rust-book/src/unsorted/abstractions.md b/embedded-rust-book/src/unsorted/abstractions.md index 6adbb468..7bf1be9b 100644 --- a/embedded-rust-book/src/unsorted/abstractions.md +++ b/embedded-rust-book/src/unsorted/abstractions.md @@ -1 +1,9 @@ # 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/embedded-rust-book/src/unsorted/embedded-linux.md b/embedded-rust-book/src/unsorted/embedded-linux.md index 5cb1aca3..c23dc93c 100644 --- a/embedded-rust-book/src/unsorted/embedded-linux.md +++ b/embedded-rust-book/src/unsorted/embedded-linux.md @@ -1 +1,9 @@ # 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/embedded-rust-book/src/unsorted/glossary.md b/embedded-rust-book/src/unsorted/glossary.md new file mode 100644 index 00000000..2434e23c --- /dev/null +++ b/embedded-rust-book/src/unsorted/glossary.md @@ -0,0 +1,3 @@ +# 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/embedded-rust-book/src/unsorted/unknown.md b/embedded-rust-book/src/unsorted/unknown.md new file mode 100644 index 00000000..0301f73d --- /dev/null +++ b/embedded-rust-book/src/unsorted/unknown.md @@ -0,0 +1,9 @@ +# 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/embedded-rust-book/src/unsorted/unlearning.md b/embedded-rust-book/src/unsorted/unlearning.md index f3d5e734..532b16a7 100644 --- a/embedded-rust-book/src/unsorted/unlearning.md +++ b/embedded-rust-book/src/unsorted/unlearning.md @@ -1 +1,12 @@ # 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/embedded-rust-book/src/unsorted/unsafe.md b/embedded-rust-book/src/unsorted/unsafe.md index cbf2b761..1191e7b7 100644 --- a/embedded-rust-book/src/unsorted/unsafe.md +++ b/embedded-rust-book/src/unsorted/unsafe.md @@ -1 +1,5 @@ # Proper use of unsafe + +> **This section should cover:** +> +> * Singletons, ownership, and the type system - "Make your assumptions machine checkable" diff --git a/embedded-rust-book/src/unsorted/unsorted.md b/embedded-rust-book/src/unsorted/unsorted.md index d972012f..694f0b7a 100644 --- a/embedded-rust-book/src/unsorted/unsorted.md +++ b/embedded-rust-book/src/unsorted/unsorted.md @@ -1 +1,3 @@ # Unsorted + +I didn't know where to put this stuff, but it should probably be rolled in somewhere... \ No newline at end of file From 583b53def6fbb8b997a8bc97d94a1889002a9cb7 Mon Sep 17 00:00:00 2001 From: James Munns Date: Sun, 1 Apr 2018 14:00:37 +0200 Subject: [PATCH 3/5] Update License information --- embedded-rust-book/LICENSE-APACHE | 201 +++++++++++++ embedded-rust-book/LICENSE-CC-BY-SA | 428 ++++++++++++++++++++++++++++ embedded-rust-book/LICENSE-MIT | 23 ++ embedded-rust-book/README.md | 9 +- 4 files changed, 660 insertions(+), 1 deletion(-) create mode 100644 embedded-rust-book/LICENSE-APACHE create mode 100644 embedded-rust-book/LICENSE-CC-BY-SA create mode 100644 embedded-rust-book/LICENSE-MIT diff --git a/embedded-rust-book/LICENSE-APACHE b/embedded-rust-book/LICENSE-APACHE new file mode 100644 index 00000000..11069edd --- /dev/null +++ b/embedded-rust-book/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/embedded-rust-book/LICENSE-CC-BY-SA b/embedded-rust-book/LICENSE-CC-BY-SA new file mode 100644 index 00000000..a73481c4 --- /dev/null +++ b/embedded-rust-book/LICENSE-CC-BY-SA @@ -0,0 +1,428 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + diff --git a/embedded-rust-book/LICENSE-MIT b/embedded-rust-book/LICENSE-MIT new file mode 100644 index 00000000..468cd79a --- /dev/null +++ b/embedded-rust-book/LICENSE-MIT @@ -0,0 +1,23 @@ +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. \ No newline at end of file diff --git a/embedded-rust-book/README.md b/embedded-rust-book/README.md index 0fd2a148..011517cd 100644 --- a/embedded-rust-book/README.md +++ b/embedded-rust-book/README.md @@ -16,4 +16,11 @@ mdbook serve ## License -Not yet determined. Likely Apache/MIT, maybe something CC. \ No newline at end of file +The Embedded Rust Book (this project) is distributed under the following licenses: + +* The code samples contained within this book are licensed under the terms of both the [MIT License] and the [Apache License v2.0]. +* The written prose contained within this book is licensed under the terms of the Creative Commons [CC-BY-SA v4.0] license. + +[MIT License]: ./LICENSE-MIT +[Apache License v2.0]: ./LICENSE-APACHE +[CC-BY-SA v4.0]: ./LICENSE-CC-BY-SA \ No newline at end of file From 2043a2a4409e2606dde2bee7bfb8976137985fb4 Mon Sep 17 00:00:00 2001 From: James Munns Date: Sun, 1 Apr 2018 14:01:20 +0200 Subject: [PATCH 4/5] Correct default mdbook port --- embedded-rust-book/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embedded-rust-book/README.md b/embedded-rust-book/README.md index 011517cd..855c98d0 100644 --- a/embedded-rust-book/README.md +++ b/embedded-rust-book/README.md @@ -11,7 +11,7 @@ cargo install mdbook cd embedded-rust-book mdbook serve -# open a web browser, go to http://localhost:3001 +# open a web browser, go to http://localhost:3000 ``` ## License From 862d0637a5e6fba234cad5876c0e7f5892846e67 Mon Sep 17 00:00:00 2001 From: James Munns Date: Sun, 1 Apr 2018 14:03:46 +0200 Subject: [PATCH 5/5] Explicitly use the F3 Discovery board for now --- embedded-rust-book/src/intro/introduction.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/embedded-rust-book/src/intro/introduction.md b/embedded-rust-book/src/intro/introduction.md index 4754f3fd..82eceeaf 100644 --- a/embedded-rust-book/src/intro/introduction.md +++ b/embedded-rust-book/src/intro/introduction.md @@ -28,9 +28,11 @@ If you are not yet comfortable with Embedded Systems, we highly suggest `LEARNIN 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. +This book will be using the [STMF3DISCOVERY] development board from STMicroelectronics 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. +For this reason, we suggest purchasing the [STMF3DISCOVERY] development board for the purpose of following this book. + +[STMF3DISCOVERY]: http://www.st.com/en/evaluation-tools/stm32f3discovery.html ## Contributing to This Book