Merge pull request #133 from rust-embedded/outline-and-intro

Book: Outline and Intro Rework

Author: japaric

books/embedded-rust-book/src/SUMMARY.md

@@ -1,38 +1,36 @@
 # Summary
 
+<!--
+
+Definition of the organization of this book is still a work in process.
+
+Refer to https://github.com/rust-lang-nursery/embedded-wg/issues/115 for
+more information and coordination
+
+-->
+
 - [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)
+- [Static Guarantees](./static-guarantees/static-guarantees.md)
+    <!-- TODO: Define Sections -->
+- [Portability](./portability/portability.md)
+    <!-- TODO: Define Sections -->
+- [Singletons](./singletons/singletons.md)
+    <!-- TODO: Define Sections -->
+- [Concurrency](./concurrency/concurrency.md)
+    <!-- TODO: Define Sections -->
+- [Dynamic Data Structures](./dynamic/dynamic.md)
+    <!-- TODO: Define Sections -->
+- [Tips for embedded C developers](./c-tips/c-tips.md)
+    <!-- TODO: Define Sections -->
+- [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)

books/embedded-rust-book/src/assets/f3.jpg

@@ -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.

books/embedded-rust-book/src/blinky/blinky.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.

books/embedded-rust-book/src/blinky/compiling.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.

books/embedded-rust-book/src/blinky/linking.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.

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

@@ -0,0 +1 @@
+# A little C with your Rust

books/embedded-rust-book/src/blinky/setup.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.

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

@@ -0,0 +1 @@
+# A little Rust with your C

books/embedded-rust-book/src/c-tips/c-tips.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")
+
+<p align="center">
+<img title="F3" src="assets/f3.jpg">
+</p>
+
+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