-* The `cxxbridge` tool is a standalone tool that generates the C++ side of the
+- The `cxxbridge` tool is a standalone tool that generates the C++ side of the
bridge module. It is included in Android and available as a Soong tool.
-* By convention, if your Rust source file is `lib.rs` your header file will be
+- By convention, if your Rust source file is `lib.rs` your header file will be
named `lib.rs.h` and your source file will be named `lib.rs.cc`. This naming
convention isn't enforced, though.
diff --git a/src/android/interoperability/cpp/bridge.md b/src/android/interoperability/cpp/bridge.md
index 6cb2958eba31..1a421a84c732 100644
--- a/src/android/interoperability/cpp/bridge.md
+++ b/src/android/interoperability/cpp/bridge.md
@@ -10,14 +10,14 @@ a Rust module annotated with the `#[cxx::bridge]` attribute macro.
-* The bridge is generally declared in an `ffi` module within your crate.
-* From the declarations made in the bridge module, CXX will generate matching
+- The bridge is generally declared in an `ffi` module within your crate.
+- From the declarations made in the bridge module, CXX will generate matching
Rust and C++ type/function definitions in order to expose those items to both
languages.
-* To view the generated Rust code, use [cargo-expand] to view the expanded proc
+- To view the generated Rust code, use [cargo-expand] to view the expanded proc
macro. For most of the examples you would use `cargo expand ::ffi` to expand
just the `ffi` module (though this doesn't apply for Android projects).
-* To view the generated C++ code, look in `target/cxxbridge`.
+- To view the generated C++ code, look in `target/cxxbridge`.
[cargo-expand]: https://github.com/dtolnay/cargo-expand
diff --git a/src/android/interoperability/cpp/cpp-bridge.md b/src/android/interoperability/cpp/cpp-bridge.md
index 50e902d0af71..08d7eeb4b82b 100644
--- a/src/android/interoperability/cpp/cpp-bridge.md
+++ b/src/android/interoperability/cpp/cpp-bridge.md
@@ -43,10 +43,10 @@ impl BlobstoreClient {
-* The programmer does not need to promise that the signatures they have typed in
+- The programmer does not need to promise that the signatures they have typed in
are accurate. CXX performs static assertions that the signatures exactly
correspond with what is declared in C++.
-* `unsafe extern` blocks allow you to declare C++ functions that are safe to
+- `unsafe extern` blocks allow you to declare C++ functions that are safe to
call from Rust.
diff --git a/src/android/interoperability/cpp/cpp-exception.md b/src/android/interoperability/cpp/cpp-exception.md
index 12c2dc6417ce..bb96b43f99aa 100644
--- a/src/android/interoperability/cpp/cpp-exception.md
+++ b/src/android/interoperability/cpp/cpp-exception.md
@@ -6,9 +6,9 @@
-* C++ functions declared to return a `Result` will catch any thrown exception on
+- C++ functions declared to return a `Result` will catch any thrown exception on
the C++ side and return it as an `Err` value to the calling Rust function.
-* If an exception is thrown from an extern "C++" function that is not declared
+- If an exception is thrown from an extern "C++" function that is not declared
by the CXX bridge to return `Result`, the program calls C++'s
`std::terminate`. The behavior is equivalent to the same exception being
thrown through a `noexcept` C++ function.
diff --git a/src/android/interoperability/cpp/rust-bridge.md b/src/android/interoperability/cpp/rust-bridge.md
index 7a55371d3bf8..59df1d015e7b 100644
--- a/src/android/interoperability/cpp/rust-bridge.md
+++ b/src/android/interoperability/cpp/rust-bridge.md
@@ -6,9 +6,9 @@
-* Items declared in the `extern "Rust"` reference items that are in scope in the
+- Items declared in the `extern "Rust"` reference items that are in scope in the
parent module.
-* The CXX code generator uses your `extern "Rust"` section(s) to produce a C++
+- The CXX code generator uses your `extern "Rust"` section(s) to produce a C++
header file containing the corresponding C++ declarations. The generated
header has the same path as the Rust source file containing the bridge, except
with a .rs.h file extension.
diff --git a/src/android/interoperability/cpp/rust-result.md b/src/android/interoperability/cpp/rust-result.md
index 0631b955ab48..5deecb00b9e6 100644
--- a/src/android/interoperability/cpp/rust-result.md
+++ b/src/android/interoperability/cpp/rust-result.md
@@ -6,12 +6,12 @@
-* Rust functions that return `Result` are translated to exceptions on the C++
+- Rust functions that return `Result` are translated to exceptions on the C++
side.
-* The exception thrown will always be of type `rust::Error`, which primarily
+- The exception thrown will always be of type `rust::Error`, which primarily
exposes a way to get the error message string. The error message will come
from the error type's `Display` impl.
-* A panic unwinding from Rust to C++ will always cause the process to
+- A panic unwinding from Rust to C++ will always cause the process to
immediately terminate.
diff --git a/src/android/interoperability/cpp/shared-enums.md b/src/android/interoperability/cpp/shared-enums.md
index dbf17d6e971e..3db15da35960 100644
--- a/src/android/interoperability/cpp/shared-enums.md
+++ b/src/android/interoperability/cpp/shared-enums.md
@@ -18,7 +18,7 @@ Generated C++:
-* On the Rust side, the code generated for shared enums is actually a struct
+- On the Rust side, the code generated for shared enums is actually a struct
wrapping a numeric value. This is because it is not UB in C++ for an enum
class to hold a value different from all of the listed variants, and our Rust
representation needs to have the same behavior.
diff --git a/src/android/interoperability/cpp/shared-types.md b/src/android/interoperability/cpp/shared-types.md
index 3ef7dfe46a47..a8994794caf5 100644
--- a/src/android/interoperability/cpp/shared-types.md
+++ b/src/android/interoperability/cpp/shared-types.md
@@ -6,8 +6,8 @@
diff --git a/src/async/control-flow/select.md b/src/async/control-flow/select.md
index 014d24aaac60..4c69a5980862 100644
--- a/src/async/control-flow/select.md
+++ b/src/async/control-flow/select.md
@@ -2,8 +2,8 @@
A select operation waits until any of a set of futures is ready, and responds to
that future's result. In JavaScript, this is similar to `Promise.race`. In
-Python, it compares to `asyncio.wait(task_set,
-return_when=asyncio.FIRST_COMPLETED)`.
+Python, it compares to
+`asyncio.wait(task_set, return_when=asyncio.FIRST_COMPLETED)`.
Similar to a match statement, the body of `select!` has a number of arms, each
of the form `pattern = future => statement`. When the `future` is ready, the
@@ -59,21 +59,21 @@ async fn main() {
-* Only C-like (unit) enums are supported.
-* A limited number of traits are supported for `#[derive()]` on shared types.
+- Only C-like (unit) enums are supported.
+- A limited number of traits are supported for `#[derive()]` on shared types.
Corresponding functionality is also generated for the C++ code, e.g. if you
derive `Hash` also generates an implementation of `std::hash` for the
corresponding C++ type.
diff --git a/src/android/interoperability/cpp/type-mapping.md b/src/android/interoperability/cpp/type-mapping.md
index 22867c8341fd..ee99cbe7b6ee 100644
--- a/src/android/interoperability/cpp/type-mapping.md
+++ b/src/android/interoperability/cpp/type-mapping.md
@@ -1,7 +1,7 @@
# Additional Types
| Rust Type | C++ Type |
-|-------------------|----------------------|
+| ----------------- | -------------------- |
| `String` | `rust::String` |
| `&str` | `rust::Str` |
| `CxxString` | `std::string` |
@@ -13,14 +13,14 @@
diff --git a/src/async/channels.md b/src/async/channels.md
index 5a58361875e5..301c0ab2b090 100644
--- a/src/async/channels.md
+++ b/src/async/channels.md
@@ -32,18 +32,18 @@ async fn main() {
-* These types can be used in the fields of shared structs and the arguments and
+- These types can be used in the fields of shared structs and the arguments and
returns of extern functions.
-* Note that Rust's `String` does not map directly to `std::string`. There are a
+- Note that Rust's `String` does not map directly to `std::string`. There are a
few reasons for this:
- * `std::string` does not uphold the UTF-8 invariant that `String` requires.
- * The two types have different layouts in memory and so can't be passed
+ - `std::string` does not uphold the UTF-8 invariant that `String` requires.
+ - The two types have different layouts in memory and so can't be passed
directly between languages.
- * `std::string` requires move constructors that don't match Rust's move
+ - `std::string` requires move constructors that don't match Rust's move
semantics, so a `std::string` can't be passed by value to Rust.
diff --git a/src/android/interoperability/java.md b/src/android/interoperability/java.md
index dde7d7a4d574..0841a65bb220 100644
--- a/src/android/interoperability/java.md
+++ b/src/android/interoperability/java.md
@@ -1,8 +1,9 @@
# Interoperability with Java
-Java can load shared objects via [Java Native Interface
-(JNI)](https://en.wikipedia.org/wiki/Java_Native_Interface). The [`jni`
-crate](https://docs.rs/jni/) allows you to create a compatible library.
+Java can load shared objects via
+[Java Native Interface (JNI)](https://en.wikipedia.org/wiki/Java_Native_Interface).
+The [`jni` crate](https://docs.rs/jni/) allows you to create a compatible
+library.
First, we create a Rust function to export to Java:
diff --git a/src/android/interoperability/with-c.md b/src/android/interoperability/with-c.md
index 152fa695c643..1f1083eac5a1 100644
--- a/src/android/interoperability/with-c.md
+++ b/src/android/interoperability/with-c.md
@@ -17,8 +17,8 @@ fn main() {
}
```
-We already saw this in the [Safe FFI Wrapper
-exercise](../../exercises/day-3/safe-ffi-wrapper.md).
+We already saw this in the
+[Safe FFI Wrapper exercise](../../exercises/day-3/safe-ffi-wrapper.md).
> This assumes full knowledge of the target platform. Not recommended for
> production.
diff --git a/src/android/interoperability/with-c/bindgen/c-library.md b/src/android/interoperability/with-c/bindgen/c-library.md
index 01ddb6dba71a..53f16a95ceaa 100644
--- a/src/android/interoperability/with-c/bindgen/c-library.md
+++ b/src/android/interoperability/with-c/bindgen/c-library.md
@@ -17,4 +17,3 @@ _interoperability/c/libbirthday/libbirthday.c_:
```c
{{#include c/libbirthday/libbirthday.c}}
```
-
diff --git a/src/android/interoperability/with-c/hand-written.md b/src/android/interoperability/with-c/hand-written.md
index abf68e634fcd..56f0f240be2d 100644
--- a/src/android/interoperability/with-c/hand-written.md
+++ b/src/android/interoperability/with-c/hand-written.md
@@ -14,8 +14,8 @@ fn main() {
}
```
-We already saw this in the [Safe FFI Wrapper
-exercise](../../exercises/day-3/safe-ffi-wrapper.md).
+We already saw this in the
+[Safe FFI Wrapper exercise](../../exercises/day-3/safe-ffi-wrapper.md).
> This assumes full knowledge of the target platform. Not recommended for
> production.
diff --git a/src/android/interoperability/with-c/rust.md b/src/android/interoperability/with-c/rust.md
index 31dd12f634e2..5a045dfbc1cb 100644
--- a/src/android/interoperability/with-c/rust.md
+++ b/src/android/interoperability/with-c/rust.md
@@ -34,7 +34,6 @@ _interoperability/rust/analyze/Android.bp_
{{#include rust/analyze/Android.bp}}
```
-
Build, push, and run the binary on your device:
```shell
@@ -43,7 +42,8 @@ Build, push, and run the binary on your device:
-`#[no_mangle]` disables Rust's usual name mangling, so the exported symbol will just be the name of
-the function. You can also use `#[export_name = "some_name"]` to specify whatever name you want.
+`#[no_mangle]` disables Rust's usual name mangling, so the exported symbol will
+just be the name of the function. You can also use
+`#[export_name = "some_name"]` to specify whatever name you want.
diff --git a/src/android/setup.md b/src/android/setup.md
index cebba74742b9..32d9d5000c92 100644
--- a/src/android/setup.md
+++ b/src/android/setup.md
@@ -1,7 +1,7 @@
# Setup
-We will be using a Cuttlefish Android Virtual Device to test our code. Make sure you
-have access to one or create a new one with:
+We will be using a Cuttlefish Android Virtual Device to test our code. Make sure
+you have access to one or create a new one with:
```shell
source build/envsetup.sh
@@ -9,15 +9,18 @@ lunch aosp_cf_x86_64_phone-trunk_staging-userdebug
acloud create
```
-Please see the [Android Developer
-Codelab](https://source.android.com/docs/setup/start) for details.
+Please see the
+[Android Developer Codelab](https://source.android.com/docs/setup/start) for
+details.
Key points:
-- Cuttlefish is a reference Android device designed to work on generic Linux desktops. MacOS support is also planned.
+- Cuttlefish is a reference Android device designed to work on generic Linux
+ desktops. MacOS support is also planned.
-- The Cuttlefish system image maintains high fidelity to real devices, and is the ideal emulator to run many Rust use cases.
+- The Cuttlefish system image maintains high fidelity to real devices, and is
+ the ideal emulator to run many Rust use cases.
diff --git a/src/async.md b/src/async.md
index b838768a141e..a0315370e87c 100644
--- a/src/async.md
+++ b/src/async.md
@@ -1,6 +1,7 @@
---
session: Afternoon
---
+
# Async Rust
"Async" is a concurrency model where multiple tasks are executed concurrently by
@@ -11,18 +12,18 @@ very low and operating systems provide primitives for efficiently identifying
I/O that is able to proceed.
Rust's asynchronous operation is based on "futures", which represent work that
-may be completed in the future. Futures are "polled" until they signal that
-they are complete.
+may be completed in the future. Futures are "polled" until they signal that they
+are complete.
Futures are polled by an async runtime, and several different runtimes are
available.
## Comparisons
- * Python has a similar model in its `asyncio`. However, its `Future` type is
- callback-based, and not polled. Async Python programs require a "loop",
- similar to a runtime in Rust.
+- Python has a similar model in its `asyncio`. However, its `Future` type is
+ callback-based, and not polled. Async Python programs require a "loop",
+ similar to a runtime in Rust.
- * JavaScript's `Promise` is similar, but again callback-based. The language
- runtime implements the event loop, so many of the details of Promise
- resolution are hidden.
+- JavaScript's `Promise` is similar, but again callback-based. The language
+ runtime implements the event loop, so many of the details of Promise
+ resolution are hidden.
diff --git a/src/async/async-await.md b/src/async/async-await.md
index 790603385456..b80d19b42604 100644
--- a/src/async/async-await.md
+++ b/src/async/async-await.md
@@ -24,25 +24,25 @@ fn main() {
Key points:
-* Note that this is a simplified example to show the syntax. There is no long
+- Note that this is a simplified example to show the syntax. There is no long
running operation or any real concurrency in it!
-* What is the return type of an async call?
- * Use `let future: () = async_main(10);` in `main` to see the type.
+- What is the return type of an async call?
+ - Use `let future: () = async_main(10);` in `main` to see the type.
-* The "async" keyword is syntactic sugar. The compiler replaces the return type
- with a future.
+- The "async" keyword is syntactic sugar. The compiler replaces the return type
+ with a future.
-* You cannot make `main` async, without additional instructions to the compiler
+- You cannot make `main` async, without additional instructions to the compiler
on how to use the returned future.
-* You need an executor to run async code. `block_on` blocks the current thread
- until the provided future has run to completion.
+- You need an executor to run async code. `block_on` blocks the current thread
+ until the provided future has run to completion.
-* `.await` asynchronously waits for the completion of another operation. Unlike
+- `.await` asynchronously waits for the completion of another operation. Unlike
`block_on`, `.await` doesn't block the current thread.
-* `.await` can only be used inside an `async` function (or block; these are
- introduced later).
+- `.await` can only be used inside an `async` function (or block; these are
+ introduced later).
-* Change the channel size to `3` and see how it affects the execution.
+- Change the channel size to `3` and see how it affects the execution.
-* Overall, the interface is similar to the `sync` channels as seen in the
+- Overall, the interface is similar to the `sync` channels as seen in the
[morning class](concurrency/channels.md).
-* Try removing the `std::mem::drop` call. What happens? Why?
+- Try removing the `std::mem::drop` call. What happens? Why?
-* The [Flume](https://docs.rs/flume/latest/flume/) crate has channels that
+- The [Flume](https://docs.rs/flume/latest/flume/) crate has channels that
implement both `sync` and `async` `send` and `recv`. This can be convenient
for complex applications with both IO and heavy CPU processing tasks.
-* What makes working with `async` channels preferable is the ability to combine
+- What makes working with `async` channels preferable is the ability to combine
them with other `future`s to combine them and create complex control flow.
diff --git a/src/async/control-flow/join.md b/src/async/control-flow/join.md
index 4a93e5c7c145..0d1015e87197 100644
--- a/src/async/control-flow/join.md
+++ b/src/async/control-flow/join.md
@@ -1,8 +1,8 @@
# Join
-A join operation waits until all of a set of futures are ready, and
-returns a collection of their results. This is similar to `Promise.all` in
-JavaScript or `asyncio.gather` in Python.
+A join operation waits until all of a set of futures are ready, and returns a
+collection of their results. This is similar to `Promise.all` in JavaScript or
+`asyncio.gather` in Python.
```rust,editable,compile_fail
use anyhow::Result;
@@ -35,16 +35,17 @@ async fn main() {
Copy this example into your prepared `src/main.rs` and run it from there.
-* For multiple futures of disjoint types, you can use `std::future::join!` but
+- For multiple futures of disjoint types, you can use `std::future::join!` but
you must know how many futures you will have at compile time. This is
currently in the `futures` crate, soon to be stabilised in `std::future`.
-* The risk of `join` is that one of the futures may never resolve, this would
- cause your program to stall.
+- The risk of `join` is that one of the futures may never resolve, this would
+ cause your program to stall.
-* You can also combine `join_all` with `join!` for instance to join all requests
+- You can also combine `join_all` with `join!` for instance to join all requests
to an http service as well as a database query. Try adding a
`tokio::time::sleep` to the future, using `futures::join!`. This is not a
- timeout (that requires `select!`, explained in the next chapter), but demonstrates `join!`.
+ timeout (that requires `select!`, explained in the next chapter), but
+ demonstrates `join!`.
-* In this example, we have a race between a cat and a dog.
+- In this example, we have a race between a cat and a dog.
`first_animal_to_finish_race` listens to both channels and will pick whichever
- arrives first. Since the dog takes 50ms, it wins against the cat that
- take 500ms.
+ arrives first. Since the dog takes 50ms, it wins against the cat that take
+ 500ms.
-* You can use `oneshot` channels in this example as the channels are supposed to
+- You can use `oneshot` channels in this example as the channels are supposed to
receive only one `send`.
-* Try adding a deadline to the race, demonstrating selecting different sorts of
+- Try adding a deadline to the race, demonstrating selecting different sorts of
futures.
-* Note that `select!` drops unmatched branches, which cancels their futures.
- It is easiest to use when every execution of `select!` creates new futures.
+- Note that `select!` drops unmatched branches, which cancels their futures. It
+ is easiest to use when every execution of `select!` creates new futures.
- * An alternative is to pass `&mut future` instead of the future itself, but
- this can lead to issues, further discussed in the pinning slide.
+ - An alternative is to pass `&mut future` instead of the future itself, but
+ this can lead to issues, further discussed in the pinning slide.
diff --git a/src/async/futures.md b/src/async/futures.md
index d9d4347c667e..60b38b78449f 100644
--- a/src/async/futures.md
+++ b/src/async/futures.md
@@ -1,8 +1,8 @@
# Futures
-[`Future`](https://doc.rust-lang.org/std/future/trait.Future.html)
-is a trait, implemented by objects that represent an operation that may not be
-complete yet. A future can be polled, and `poll` returns a
+[`Future`](https://doc.rust-lang.org/std/future/trait.Future.html) is a trait,
+implemented by objects that represent an operation that may not be complete yet.
+A future can be polled, and `poll` returns a
[`Poll`](https://doc.rust-lang.org/std/task/enum.Poll.html).
```rust
@@ -29,16 +29,16 @@ pause until that Future is ready, and then evaluates to its output.
-* The `Future` and `Poll` types are implemented exactly as shown; click the
+- The `Future` and `Poll` types are implemented exactly as shown; click the
links to show the implementations in the docs.
-* We will not get to `Pin` and `Context`, as we will focus on writing async
+- We will not get to `Pin` and `Context`, as we will focus on writing async
code, rather than building new async primitives. Briefly:
- * `Context` allows a Future to schedule itself to be polled again when an
+ - `Context` allows a Future to schedule itself to be polled again when an
event occurs.
- * `Pin` ensures that the Future isn't moved in memory, so that pointers into
+ - `Pin` ensures that the Future isn't moved in memory, so that pointers into
that future remain valid. This is required to allow references to remain
valid after an `.await`.
diff --git a/src/async/pitfalls.md b/src/async/pitfalls.md
index b025ef5b60c2..924c9c1cc727 100644
--- a/src/async/pitfalls.md
+++ b/src/async/pitfalls.md
@@ -1,6 +1,8 @@
# Pitfalls of async/await
-Async / await provides convenient and efficient abstraction for concurrent asynchronous programming. However, the async/await model in Rust also comes with its share of pitfalls and footguns. We illustrate some of them in this chapter:
+Async / await provides convenient and efficient abstraction for concurrent
+asynchronous programming. However, the async/await model in Rust also comes with
+its share of pitfalls and footguns. We illustrate some of them in this chapter:
- [Blocking the Executor](pitfalls/blocking-executor.md)
- [Pin](pitfalls/pin.md)
diff --git a/src/async/pitfalls/async-traits.md b/src/async/pitfalls/async-traits.md
index a4ea8a011cbf..626f485f7a1e 100644
--- a/src/async/pitfalls/async-traits.md
+++ b/src/async/pitfalls/async-traits.md
@@ -1,8 +1,10 @@
# Async Traits
-Async methods in traits are not yet supported in the stable channel ([An experimental feature exists in nightly and should be stabilized in the mid term.](https://blog.rust-lang.org/inside-rust/2022/11/17/async-fn-in-trait-nightly.html))
+Async methods in traits are not yet supported in the stable channel
+([An experimental feature exists in nightly and should be stabilized in the mid term.](https://blog.rust-lang.org/inside-rust/2022/11/17/async-fn-in-trait-nightly.html))
-The crate [async_trait](https://docs.rs/async-trait/latest/async_trait/) provides a workaround through a macro:
+The crate [async_trait](https://docs.rs/async-trait/latest/async_trait/)
+provides a workaround through a macro:
```rust,editable,compile_fail
use async_trait::async_trait;
@@ -46,18 +48,18 @@ async fn main() {
}
```
-
+
-* `async_trait` is easy to use, but note that it's using heap allocations to
+- `async_trait` is easy to use, but note that it's using heap allocations to
achieve this. This heap allocation has performance overhead.
-* The challenges in language support for `async trait` are deep Rust and
+- The challenges in language support for `async trait` are deep Rust and
probably not worth describing in-depth. Niko Matsakis did a good job of
- explaining them in [this
- post](https://smallcultfollowing.com/babysteps/blog/2019/10/26/async-fn-in-traits-are-hard/)
+ explaining them in
+ [this post](https://smallcultfollowing.com/babysteps/blog/2019/10/26/async-fn-in-traits-are-hard/)
if you are interested in digging deeper.
-* Try creating a new sleeper struct that will sleep for a random amount of time
+- Try creating a new sleeper struct that will sleep for a random amount of time
and adding it to the Vec.
diff --git a/src/async/pitfalls/blocking-executor.md b/src/async/pitfalls/blocking-executor.md
index cfbfb4675fd4..2ec6d1fb4f50 100644
--- a/src/async/pitfalls/blocking-executor.md
+++ b/src/async/pitfalls/blocking-executor.md
@@ -1,8 +1,8 @@
# Blocking the executor
-Most async runtimes only allow IO tasks to run concurrently.
-This means that CPU blocking tasks will block the executor and prevent other tasks from being executed.
-An easy workaround is to use async equivalent methods where possible.
+Most async runtimes only allow IO tasks to run concurrently. This means that CPU
+blocking tasks will block the executor and prevent other tasks from being
+executed. An easy workaround is to use async equivalent methods where possible.
```rust,editable,compile_fail
use futures::future::join_all;
@@ -26,25 +26,25 @@ async fn main() {
-* Run the code and see that the sleeps happen consecutively rather than
+- Run the code and see that the sleeps happen consecutively rather than
concurrently.
-* The `"current_thread"` flavor puts all tasks on a single thread. This makes the
- effect more obvious, but the bug is still present in the multi-threaded
+- The `"current_thread"` flavor puts all tasks on a single thread. This makes
+ the effect more obvious, but the bug is still present in the multi-threaded
flavor.
-* Switch the `std::thread::sleep` to `tokio::time::sleep` and await its result.
+- Switch the `std::thread::sleep` to `tokio::time::sleep` and await its result.
-* Another fix would be to `tokio::task::spawn_blocking` which spawns an actual
+- Another fix would be to `tokio::task::spawn_blocking` which spawns an actual
thread and transforms its handle into a future without blocking the executor.
-* You should not think of tasks as OS threads. They do not map 1 to 1 and most
+- You should not think of tasks as OS threads. They do not map 1 to 1 and most
executors will allow many tasks to run on a single OS thread. This is
particularly problematic when interacting with other libraries via FFI, where
that library might depend on thread-local storage or map to specific OS
threads (e.g., CUDA). Prefer `tokio::task::spawn_blocking` in such situations.
-* Use sync mutexes with care. Holding a mutex over an `.await` may cause another
+- Use sync mutexes with care. Holding a mutex over an `.await` may cause another
task to block, and that task may be running on the same thread.
diff --git a/src/async/pitfalls/cancellation.md b/src/async/pitfalls/cancellation.md
index cf4aba1832a3..7d2b0886b4f1 100644
--- a/src/async/pitfalls/cancellation.md
+++ b/src/async/pitfalls/cancellation.md
@@ -1,9 +1,9 @@
# Cancellation
-Dropping a future implies it can never be polled again. This is called *cancellation*
-and it can occur at any `await` point. Care is needed to ensure the system works
-correctly even when futures are cancelled. For example, it shouldn't deadlock or
-lose data.
+Dropping a future implies it can never be polled again. This is called
+_cancellation_ and it can occur at any `await` point. Care is needed to ensure
+the system works correctly even when futures are cancelled. For example, it
+shouldn't deadlock or lose data.
```rust,editable,compile_fail
use std::io::{self, ErrorKind};
@@ -69,46 +69,49 @@ async fn main() -> std::io::Result<()> {
-* The compiler doesn't help with cancellation-safety. You need to read API
+- The compiler doesn't help with cancellation-safety. You need to read API
documentation and consider what state your `async fn` holds.
-* Unlike `panic` and `?`, cancellation is part of normal control flow
- (vs error-handling).
+- Unlike `panic` and `?`, cancellation is part of normal control flow (vs
+ error-handling).
-* The example loses parts of the string.
+- The example loses parts of the string.
- * Whenever the `tick()` branch finishes first, `next()` and its `buf` are dropped.
+ - Whenever the `tick()` branch finishes first, `next()` and its `buf` are
+ dropped.
- * `LinesReader` can be made cancellation-safe by making `buf` part of the struct:
- ```rust,compile_fail
- struct LinesReader {
- stream: DuplexStream,
- bytes: Vec,
- buf: [u8; 1],
- }
+ - `LinesReader` can be made cancellation-safe by making `buf` part of the
+ struct:
+ ```rust,compile_fail
+ struct LinesReader {
+ stream: DuplexStream,
+ bytes: Vec,
+ buf: [u8; 1],
+ }
- impl LinesReader {
- fn new(stream: DuplexStream) -> Self {
- Self { stream, bytes: Vec::new(), buf: [0] }
- }
- async fn next(&mut self) -> io::Result> {
- // prefix buf and bytes with self.
- // ...
- let raw = std::mem::take(&mut self.bytes);
- let s = String::from_utf8(raw)
- // ...
- }
+ impl LinesReader {
+ fn new(stream: DuplexStream) -> Self {
+ Self { stream, bytes: Vec::new(), buf: [0] }
+ }
+ async fn next(&mut self) -> io::Result> {
+ // prefix buf and bytes with self.
+ // ...
+ let raw = std::mem::take(&mut self.bytes);
+ let s = String::from_utf8(raw)
+ // ...
}
- ```
+ }
+ ```
-* [`Interval::tick`](https://docs.rs/tokio/latest/tokio/time/struct.Interval.html#method.tick)
- is cancellation-safe because it keeps track of whether a tick has been 'delivered'.
+- [`Interval::tick`](https://docs.rs/tokio/latest/tokio/time/struct.Interval.html#method.tick)
+ is cancellation-safe because it keeps track of whether a tick has been
+ 'delivered'.
-* [`AsyncReadExt::read`](https://docs.rs/tokio/latest/tokio/io/trait.AsyncReadExt.html#method.read)
+- [`AsyncReadExt::read`](https://docs.rs/tokio/latest/tokio/io/trait.AsyncReadExt.html#method.read)
is cancellation-safe because it either returns or doesn't read data.
-* [`AsyncBufReadExt::read_line`](https://docs.rs/tokio/latest/tokio/io/trait.AsyncBufReadExt.html#method.read_line)
- is similar to the example and *isn't* cancellation-safe. See its documentation
+- [`AsyncBufReadExt::read_line`](https://docs.rs/tokio/latest/tokio/io/trait.AsyncBufReadExt.html#method.read_line)
+ is similar to the example and _isn't_ cancellation-safe. See its documentation
for details and alternatives.
diff --git a/src/async/pitfalls/pin.md b/src/async/pitfalls/pin.md
index a6f85b73d4c3..11238106eff1 100644
--- a/src/async/pitfalls/pin.md
+++ b/src/async/pitfalls/pin.md
@@ -1,9 +1,9 @@
# `Pin`
When you await a future, all local variables (that would ordinarily be stored on
-a stack frame) are instead stored in the Future for the current async block. If your
-future has pointers to data on the stack, those pointers might get invalidated.
-This is unsafe.
+a stack frame) are instead stored in the Future for the current async block. If
+your future has pointers to data on the stack, those pointers might get
+invalidated. This is unsafe.
Therefore, you must guarantee that the addresses your future points to don't
change. That is why we need to "pin" futures. Using the same future repeatedly
@@ -65,48 +65,49 @@ async fn main() {
-* You may recognize this as an example of the actor pattern. Actors
- typically call `select!` in a loop.
+- You may recognize this as an example of the actor pattern. Actors typically
+ call `select!` in a loop.
-* This serves as a summation of a few of the previous lessons, so take your time
+- This serves as a summation of a few of the previous lessons, so take your time
with it.
- * Naively add a `_ = sleep(Duration::from_millis(100)) => { println!(..) }`
- to the `select!`. This will never execute. Why?
+ - Naively add a `_ = sleep(Duration::from_millis(100)) => { println!(..) }` to
+ the `select!`. This will never execute. Why?
- * Instead, add a `timeout_fut` containing that future outside of the `loop`:
+ - Instead, add a `timeout_fut` containing that future outside of the `loop`:
- ```rust,compile_fail
- let mut timeout_fut = sleep(Duration::from_millis(100));
- loop {
- select! {
- ..,
- _ = timeout_fut => { println!(..); },
- }
+ ```rust,compile_fail
+ let mut timeout_fut = sleep(Duration::from_millis(100));
+ loop {
+ select! {
+ ..,
+ _ = timeout_fut => { println!(..); },
}
- ```
- * This still doesn't work. Follow the compiler errors, adding `&mut` to the
- `timeout_fut` in the `select!` to work around the move, then using
- `Box::pin`:
-
- ```rust,compile_fail
- let mut timeout_fut = Box::pin(sleep(Duration::from_millis(100)));
- loop {
- select! {
- ..,
- _ = &mut timeout_fut => { println!(..); },
- }
+ }
+ ```
+ - This still doesn't work. Follow the compiler errors, adding `&mut` to the
+ `timeout_fut` in the `select!` to work around the move, then using
+ `Box::pin`:
+
+ ```rust,compile_fail
+ let mut timeout_fut = Box::pin(sleep(Duration::from_millis(100)));
+ loop {
+ select! {
+ ..,
+ _ = &mut timeout_fut => { println!(..); },
}
- ```
+ }
+ ```
- * This compiles, but once the timeout expires it is `Poll::Ready` on every
- iteration (a fused future would help with this). Update to reset
- `timeout_fut` every time it expires.
+ - This compiles, but once the timeout expires it is `Poll::Ready` on every
+ iteration (a fused future would help with this). Update to reset
+ `timeout_fut` every time it expires.
-* Box allocates on the heap. In some cases, `std::pin::pin!` (only recently
+- Box allocates on the heap. In some cases, `std::pin::pin!` (only recently
stabilized, with older code often using `tokio::pin!`) is also an option, but
that is difficult to use for a future that is reassigned.
-* Another alternative is to not use `pin` at all but spawn another task that will send to a `oneshot` channel every 100ms.
+- Another alternative is to not use `pin` at all but spawn another task that
+ will send to a `oneshot` channel every 100ms.
diff --git a/src/async/runtimes.md b/src/async/runtimes.md
index 9d2888aa5425..6b03541b796d 100644
--- a/src/async/runtimes.md
+++ b/src/async/runtimes.md
@@ -1,15 +1,15 @@
# Runtimes
-A *runtime* provides support for performing operations asynchronously (a
-*reactor*) and is responsible for executing futures (an *executor*). Rust does not have a
-"built-in" runtime, but several options are available:
+A _runtime_ provides support for performing operations asynchronously (a
+_reactor_) and is responsible for executing futures (an _executor_). Rust does
+not have a "built-in" runtime, but several options are available:
- * [Tokio](https://tokio.rs/): performant, with a well-developed ecosystem of
- functionality like [Hyper](https://hyper.rs/) for HTTP or
- [Tonic](https://github.com/hyperium/tonic) for gRPC.
- * [async-std](https://async.rs/): aims to be a "std for async", and includes a
- basic runtime in `async::task`.
- * [smol](https://docs.rs/smol/latest/smol/): simple and lightweight
+- [Tokio](https://tokio.rs/): performant, with a well-developed ecosystem of
+ functionality like [Hyper](https://hyper.rs/) for HTTP or
+ [Tonic](https://github.com/hyperium/tonic) for gRPC.
+- [async-std](https://async.rs/): aims to be a "std for async", and includes a
+ basic runtime in `async::task`.
+- [smol](https://docs.rs/smol/latest/smol/): simple and lightweight
Several larger applications have their own runtimes. For example,
[Fuchsia](https://fuchsia.googlesource.com/fuchsia/+/refs/heads/main/src/lib/fuchsia-async/src/lib.rs)
@@ -17,11 +17,11 @@ already has one.
-* Note that of the listed runtimes, only Tokio is supported in the Rust
+- Note that of the listed runtimes, only Tokio is supported in the Rust
playground. The playground also does not permit any I/O, so most interesting
async things can't run in the playground.
-* Futures are "inert" in that they do not do anything (not even start an I/O
+- Futures are "inert" in that they do not do anything (not even start an I/O
operation) unless there is an executor polling them. This differs from JS
Promises, for example, which will run to completion even if they are never
used.
diff --git a/src/async/runtimes/tokio.md b/src/async/runtimes/tokio.md
index c9dfbd485e2b..73a7bc179239 100644
--- a/src/async/runtimes/tokio.md
+++ b/src/async/runtimes/tokio.md
@@ -1,11 +1,10 @@
# Tokio
+Tokio provides:
-Tokio provides:
-
-* A multi-threaded runtime for executing asynchronous code.
-* An asynchronous version of the standard library.
-* A large ecosystem of libraries.
+- A multi-threaded runtime for executing asynchronous code.
+- An asynchronous version of the standard library.
+- A large ecosystem of libraries.
```rust,editable,compile_fail
use tokio::time;
@@ -30,20 +29,20 @@ async fn main() {
diff --git a/src/bare-metal.md b/src/bare-metal.md
index e6479ed2ef40..f9101cde9b20 100644
--- a/src/bare-metal.md
+++ b/src/bare-metal.md
@@ -2,27 +2,32 @@
course: Bare Metal
session: Morning
---
+
# Welcome to Bare Metal Rust
-This is a standalone one-day course about bare-metal Rust, aimed at people who are familiar with the
-basics of Rust (perhaps from completing the Comprehensive Rust course), and ideally also have some
-experience with bare-metal programming in some other language such as C.
+This is a standalone one-day course about bare-metal Rust, aimed at people who
+are familiar with the basics of Rust (perhaps from completing the Comprehensive
+Rust course), and ideally also have some experience with bare-metal programming
+in some other language such as C.
-Today we will talk about 'bare-metal' Rust: running Rust code without an OS underneath us. This will
-be divided into several parts:
+Today we will talk about 'bare-metal' Rust: running Rust code without an OS
+underneath us. This will be divided into several parts:
- What is `no_std` Rust?
- Writing firmware for microcontrollers.
- Writing bootloader / kernel code for application processors.
- Some useful crates for bare-metal Rust development.
-For the microcontroller part of the course we will use the [BBC micro:bit](https://microbit.org/) v2
-as an example. It's a [development board](https://tech.microbit.org/hardware/) based on the Nordic
-nRF51822 microcontroller with some LEDs and buttons, an I2C-connected accelerometer and compass, and
-an on-board SWD debugger.
+For the microcontroller part of the course we will use the
+[BBC micro:bit](https://microbit.org/) v2 as an example. It's a
+[development board](https://tech.microbit.org/hardware/) based on the Nordic
+nRF51822 microcontroller with some LEDs and buttons, an I2C-connected
+accelerometer and compass, and an on-board SWD debugger.
To get started, install some tools we'll need later. On gLinux or Debian:
+
+
```bash
sudo apt install gcc-aarch64-linux-gnu gdb-multiarch libudev-dev picocom pkg-config qemu-system-arm
rustup update
@@ -32,7 +37,9 @@ cargo install cargo-binutils cargo-embed
```
And give users in the `plugdev` group access to the micro:bit programmer:
+
+
```bash
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0d28", MODE="0664", GROUP="plugdev"' |\
sudo tee /etc/udev/rules.d/50-microbit.rules
@@ -40,7 +47,9 @@ sudo udevadm control --reload-rules
```
On MacOS:
+
+
```bash
xcode-select --install
brew install gdb picocom qemu
diff --git a/src/bare-metal/alloc.md b/src/bare-metal/alloc.md
index e600b79994cb..91dac1a53ea4 100644
--- a/src/bare-metal/alloc.md
+++ b/src/bare-metal/alloc.md
@@ -9,14 +9,16 @@ To use `alloc` you must implement a
-* With the `tokio::main` macro we can now make `main` async.
+- With the `tokio::main` macro we can now make `main` async.
-* The `spawn` function creates a new, concurrent "task".
+- The `spawn` function creates a new, concurrent "task".
-* Note: `spawn` takes a `Future`, you don't call `.await` on `count_to`.
+- Note: `spawn` takes a `Future`, you don't call `.await` on `count_to`.
**Further exploration:**
-* Why does `count_to` not (usually) get to 10? This is an example of async
+- Why does `count_to` not (usually) get to 10? This is an example of async
cancellation. `tokio::spawn` returns a handle which can be awaited to wait
until it finishes.
-* Try `count_to(10).await` instead of spawning.
+- Try `count_to(10).await` instead of spawning.
-* Try awaiting the task returned from `tokio::spawn`.
+- Try awaiting the task returned from `tokio::spawn`.
diff --git a/src/async/tasks.md b/src/async/tasks.md
index 7dd39c606ec3..c25c626dce0e 100644
--- a/src/async/tasks.md
+++ b/src/async/tasks.md
@@ -51,15 +51,18 @@ async fn main() -> io::Result<()> {
Copy this example into your prepared `src/main.rs` and run it from there.
-Try connecting to it with a TCP connection tool like [nc](https://www.unix.com/man-page/linux/1/nc/) or [telnet](https://www.unix.com/man-page/linux/1/telnet/).
+Try connecting to it with a TCP connection tool like
+[nc](https://www.unix.com/man-page/linux/1/nc/) or
+[telnet](https://www.unix.com/man-page/linux/1/telnet/).
-* Ask students to visualize what the state of the example server would be with a
+- Ask students to visualize what the state of the example server would be with a
few connected clients. What tasks exist? What are their Futures?
-* This is the first time we've seen an `async` block. This is similar to a
+- This is the first time we've seen an `async` block. This is similar to a
closure, but does not take any arguments. Its return value is a Future,
- similar to an `async fn`.
+ similar to an `async fn`.
-* Refactor the async block into a function, and improve the error handling using `?`.
+- Refactor the async block into a function, and improve the error handling using
+ `?`.
-* `buddy_system_allocator` is a third-party crate implementing a basic buddy system allocator. Other
- crates are available, or you can write your own or hook into your existing allocator.
-* The const parameter of `LockedHeap` is the max order of the allocator; i.e. in this case it can
- allocate regions of up to 2**32 bytes.
-* If any crate in your dependency tree depends on `alloc` then you must have exactly one global
- allocator defined in your binary. Usually this is done in the top-level binary crate.
-* `extern crate panic_halt as _` is necessary to ensure that the `panic_halt` crate is linked in so
- we get its panic handler.
-* This example will build but not run, as it doesn't have an entry point.
+- `buddy_system_allocator` is a third-party crate implementing a basic buddy
+ system allocator. Other crates are available, or you can write your own or
+ hook into your existing allocator.
+- The const parameter of `LockedHeap` is the max order of the allocator; i.e. in
+ this case it can allocate regions of up to 2**32 bytes.
+- If any crate in your dependency tree depends on `alloc` then you must have
+ exactly one global allocator defined in your binary. Usually this is done in
+ the top-level binary crate.
+- `extern crate panic_halt as _` is necessary to ensure that the `panic_halt`
+ crate is linked in so we get its panic handler.
+- This example will build but not run, as it doesn't have an entry point.
diff --git a/src/bare-metal/android.md b/src/bare-metal/android.md
index 89c95d5f008a..c581f0ec5ef0 100644
--- a/src/bare-metal/android.md
+++ b/src/bare-metal/android.md
@@ -1,9 +1,12 @@
# Android
-To build a bare-metal Rust binary in AOSP, you need to use a `rust_ffi_static` Soong rule to build
-your Rust code, then a `cc_binary` with a linker script to produce the binary itself, and then a
-`raw_binary` to convert the ELF to a raw binary ready to be run.
+To build a bare-metal Rust binary in AOSP, you need to use a `rust_ffi_static`
+Soong rule to build your Rust code, then a `cc_binary` with a linker script to
+produce the binary itself, and then a `raw_binary` to convert the ELF to a raw
+binary ready to be run.
+
+
```soong
rust_ffi_static {
name: "libvmbase_example",
diff --git a/src/bare-metal/android/vmbase.md b/src/bare-metal/android/vmbase.md
index 12bc288ecc3c..417c4daebc74 100644
--- a/src/bare-metal/android/vmbase.md
+++ b/src/bare-metal/android/vmbase.md
@@ -1,8 +1,11 @@
# vmbase
-For VMs running under crosvm on aarch64, the [vmbase][1] library provides a linker script and useful
-defaults for the build rules, along with an entry point, UART console logging and more.
+For VMs running under crosvm on aarch64, the [vmbase][1] library provides a
+linker script and useful defaults for the build rules, along with an entry
+point, UART console logging and more.
+
+
```rust,compile_fail
#![no_main]
#![no_std]
@@ -18,9 +21,10 @@ pub fn main(arg0: u64, arg1: u64, arg2: u64, arg3: u64) {
-* The `main!` macro marks your main function, to be called from the `vmbase` entry point.
-* The `vmbase` entry point handles console initialisation, and issues a PSCI_SYSTEM_OFF to shutdown
- the VM if your main function returns.
+- The `main!` macro marks your main function, to be called from the `vmbase`
+ entry point.
+- The `vmbase` entry point handles console initialisation, and issues a
+ PSCI_SYSTEM_OFF to shutdown the VM if your main function returns.
diff --git a/src/bare-metal/aps.md b/src/bare-metal/aps.md
index ace7c620c568..82ebf7f5f8e9 100644
--- a/src/bare-metal/aps.md
+++ b/src/bare-metal/aps.md
@@ -1,18 +1,21 @@
---
session: Afternoon
---
+
# Application processors
-So far we've talked about microcontrollers, such as the Arm Cortex-M series. Now let's try writing
-something for Cortex-A. For simplicity we'll just work with QEMU's aarch64
+So far we've talked about microcontrollers, such as the Arm Cortex-M series. Now
+let's try writing something for Cortex-A. For simplicity we'll just work with
+QEMU's aarch64
['virt'](https://qemu-project.gitlab.io/qemu/system/arm/virt.html) board.
-* Broadly speaking, microcontrollers don't have an MMU or multiple levels of privilege (exception
- levels on Arm CPUs, rings on x86), while application processors do.
-* QEMU supports emulating various different machines or board models for each architecture. The
- 'virt' board doesn't correspond to any particular real hardware, but is designed purely for
- virtual machines.
+- Broadly speaking, microcontrollers don't have an MMU or multiple levels of
+ privilege (exception levels on Arm CPUs, rings on x86), while application
+ processors do.
+- QEMU supports emulating various different machines or board models for each
+ architecture. The 'virt' board doesn't correspond to any particular real
+ hardware, but is designed purely for virtual machines.
diff --git a/src/bare-metal/aps/better-uart.md b/src/bare-metal/aps/better-uart.md
index 99ceb51df77e..f87fca7c4020 100644
--- a/src/bare-metal/aps/better-uart.md
+++ b/src/bare-metal/aps/better-uart.md
@@ -1,8 +1,8 @@
# A better UART driver
-The PL011 actually has [a bunch more registers][1], and adding offsets to construct pointers to access
-them is error-prone and hard to read. Plus, some of them are bit fields which would be nice to
-access in a structured way.
+The PL011 actually has [a bunch more registers][1], and adding offsets to
+construct pointers to access them is error-prone and hard to read. Plus, some of
+them are bit fields which would be nice to access in a structured way.
| Offset | Register name | Width |
| ------ | ------------- | ----- |
diff --git a/src/bare-metal/aps/better-uart/bitflags.md b/src/bare-metal/aps/better-uart/bitflags.md
index 0ee6c0c5a9b1..891cd2e0592e 100644
--- a/src/bare-metal/aps/better-uart/bitflags.md
+++ b/src/bare-metal/aps/better-uart/bitflags.md
@@ -1,6 +1,7 @@
# Bitflags
-The [`bitflags`](https://crates.io/crates/bitflags) crate is useful for working with bitflags.
+The [`bitflags`](https://crates.io/crates/bitflags) crate is useful for working
+with bitflags.
```rust,editable,compile_fail
{{#include ../examples/src/pl011.rs:Flags}}
@@ -8,7 +9,7 @@ The [`bitflags`](https://crates.io/crates/bitflags) crate is useful for working
-* The `bitflags!` macro creates a newtype something like `Flags(u16)`, along with a bunch of method
- implementations to get and set flags.
+- The `bitflags!` macro creates a newtype something like `Flags(u16)`, along
+ with a bunch of method implementations to get and set flags.
diff --git a/src/bare-metal/aps/better-uart/driver.md b/src/bare-metal/aps/better-uart/driver.md
index 28bad722076d..64c432edf203 100644
--- a/src/bare-metal/aps/better-uart/driver.md
+++ b/src/bare-metal/aps/better-uart/driver.md
@@ -8,7 +8,7 @@ Now let's use the new `Registers` struct in our driver.
-* Note the use of `addr_of!` / `addr_of_mut!` to get pointers to individual fields without creating
- an intermediate reference, which would be unsound.
+- Note the use of `addr_of!` / `addr_of_mut!` to get pointers to individual
+ fields without creating an intermediate reference, which would be unsound.
diff --git a/src/bare-metal/aps/better-uart/registers.md b/src/bare-metal/aps/better-uart/registers.md
index 3cd8d3349d7d..48f5e5b1bfb9 100644
--- a/src/bare-metal/aps/better-uart/registers.md
+++ b/src/bare-metal/aps/better-uart/registers.md
@@ -1,16 +1,19 @@
# Multiple registers
We can use a struct to represent the memory layout of the UART's registers.
+
+
```rust,editable,compile_fail
{{#include ../examples/src/pl011.rs:Registers}}
```
-* [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation) tells
- the compiler to lay the struct fields out in order, following the same rules as C. This is
- necessary for our struct to have a predictable layout, as default Rust representation allows the
- compiler to (among other things) reorder fields however it sees fit.
+- [`#[repr(C)]`](https://doc.rust-lang.org/reference/type-layout.html#the-c-representation)
+ tells the compiler to lay the struct fields out in order, following the same
+ rules as C. This is necessary for our struct to have a predictable layout, as
+ default Rust representation allows the compiler to (among other things)
+ reorder fields however it sees fit.
diff --git a/src/bare-metal/aps/better-uart/using.md b/src/bare-metal/aps/better-uart/using.md
index 5089224c3d8b..159c8e3db479 100644
--- a/src/bare-metal/aps/better-uart/using.md
+++ b/src/bare-metal/aps/better-uart/using.md
@@ -1,7 +1,7 @@
# Using it
-Let's write a small program using our driver to write to the serial console, and echo incoming
-bytes.
+Let's write a small program using our driver to write to the serial console, and
+echo incoming bytes.
```rust,editable,compile_fail
{{#include ../examples/src/main_improved.rs:main}}
@@ -9,8 +9,9 @@ bytes.
-* As in the [inline assembly](../inline-assembly.md) example, this `main` function is called from our
- entry point code in `entry.S`. See the speaker notes there for details.
-* Run the example in QEMU with `make qemu` under `src/bare-metal/aps/examples`.
+- As in the [inline assembly](../inline-assembly.md) example, this `main`
+ function is called from our entry point code in `entry.S`. See the speaker
+ notes there for details.
+- Run the example in QEMU with `make qemu` under `src/bare-metal/aps/examples`.
diff --git a/src/bare-metal/aps/entry-point.md b/src/bare-metal/aps/entry-point.md
index b40005d12427..783e73df6323 100644
--- a/src/bare-metal/aps/entry-point.md
+++ b/src/bare-metal/aps/entry-point.md
@@ -8,28 +8,36 @@ Before we can start running Rust code, we need to do some initialisation.
-* This is the same as it would be for C: initialising the processor state, zeroing the BSS, and
- setting up the stack pointer.
- * The BSS (block starting symbol, for historical reasons) is the part of the object file which
- containing statically allocated variables which are initialised to zero. They are omitted from
- the image, to avoid wasting space on zeroes. The compiler assumes that the loader will take care
- of zeroing them.
-* The BSS may already be zeroed, depending on how memory is initialised and the image is loaded, but
- we zero it to be sure.
-* We need to enable the MMU and cache before reading or writing any memory. If we don't:
- * Unaligned accesses will fault. We build the Rust code for the `aarch64-unknown-none` target
- which sets `+strict-align` to prevent the compiler generating unaligned accesses, so it should
- be fine in this case, but this is not necessarily the case in general.
- * If it were running in a VM, this can lead to cache coherency issues. The problem is that the VM
- is accessing memory directly with the cache disabled, while the host has cacheable aliases to the
- same memory. Even if the host doesn't explicitly access the memory, speculative accesses can
- lead to cache fills, and then changes from one or the other will get lost when the cache is
- cleaned or the VM enables the cache. (Cache is keyed by physical address, not VA or IPA.)
-* For simplicity, we just use a hardcoded pagetable (see `idmap.S`) which identity maps the first 1
- GiB of address space for devices, the next 1 GiB for DRAM, and another 1 GiB higher up for more
- devices. This matches the memory layout that QEMU uses.
-* We also set up the exception vector (`vbar_el1`), which we'll see more about later.
-* All examples this afternoon assume we will be running at exception level 1 (EL1). If you need to
- run at a different exception level you'll need to modify `entry.S` accordingly.
+- This is the same as it would be for C: initialising the processor state,
+ zeroing the BSS, and setting up the stack pointer.
+ - The BSS (block starting symbol, for historical reasons) is the part of the
+ object file which containing statically allocated variables which are
+ initialised to zero. They are omitted from the image, to avoid wasting space
+ on zeroes. The compiler assumes that the loader will take care of zeroing
+ them.
+- The BSS may already be zeroed, depending on how memory is initialised and the
+ image is loaded, but we zero it to be sure.
+- We need to enable the MMU and cache before reading or writing any memory. If
+ we don't:
+ - Unaligned accesses will fault. We build the Rust code for the
+ `aarch64-unknown-none` target which sets `+strict-align` to prevent the
+ compiler generating unaligned accesses, so it should be fine in this case,
+ but this is not necessarily the case in general.
+ - If it were running in a VM, this can lead to cache coherency issues. The
+ problem is that the VM is accessing memory directly with the cache disabled,
+ while the host has cacheable aliases to the same memory. Even if the host
+ doesn't explicitly access the memory, speculative accesses can lead to cache
+ fills, and then changes from one or the other will get lost when the cache
+ is cleaned or the VM enables the cache. (Cache is keyed by physical address,
+ not VA or IPA.)
+- For simplicity, we just use a hardcoded pagetable (see `idmap.S`) which
+ identity maps the first 1 GiB of address space for devices, the next 1 GiB for
+ DRAM, and another 1 GiB higher up for more devices. This matches the memory
+ layout that QEMU uses.
+- We also set up the exception vector (`vbar_el1`), which we'll see more about
+ later.
+- All examples this afternoon assume we will be running at exception level 1
+ (EL1). If you need to run at a different exception level you'll need to modify
+ `entry.S` accordingly.
diff --git a/src/bare-metal/aps/exceptions.md b/src/bare-metal/aps/exceptions.md
index e8bf4a94a36c..916d952fbc6b 100644
--- a/src/bare-metal/aps/exceptions.md
+++ b/src/bare-metal/aps/exceptions.md
@@ -1,26 +1,30 @@
# Exceptions
-AArch64 defines an exception vector table with 16 entries, for 4 types of exceptions (synchronous,
-IRQ, FIQ, SError) from 4 states (current EL with SP0, current EL with SPx, lower EL using AArch64,
-lower EL using AArch32). We implement this in assembly to save volatile registers to the stack
-before calling into Rust code:
+AArch64 defines an exception vector table with 16 entries, for 4 types of
+exceptions (synchronous, IRQ, FIQ, SError) from 4 states (current EL with SP0,
+current EL with SPx, lower EL using AArch64, lower EL using AArch32). We
+implement this in assembly to save volatile registers to the stack before
+calling into Rust code:
+
+
```rust,editable,compile_fail
{{#include examples/src/exceptions.rs:exceptions}}
```
-* EL is exception level; all our examples this afternoon run in EL1.
-* For simplicity we aren't distinguishing between SP0 and SPx for the current EL exceptions, or
- between AArch32 and AArch64 for the lower EL exceptions.
-* For this example we just log the exception and power down, as we don't expect any of them to
- actually happen.
-* We can think of exception handlers and our main execution context more or less like different
- threads. [`Send` and `Sync`][1] will control what we can share between them, just like with threads.
- For example, if we want to share some value between exception handlers and the rest of the
- program, and it's `Send` but not `Sync`, then we'll need to wrap it in something like a `Mutex`
- and put it in a static.
+- EL is exception level; all our examples this afternoon run in EL1.
+- For simplicity we aren't distinguishing between SP0 and SPx for the current EL
+ exceptions, or between AArch32 and AArch64 for the lower EL exceptions.
+- For this example we just log the exception and power down, as we don't expect
+ any of them to actually happen.
+- We can think of exception handlers and our main execution context more or less
+ like different threads. [`Send` and `Sync`][1] will control what we can share
+ between them, just like with threads. For example, if we want to share some
+ value between exception handlers and the rest of the program, and it's `Send`
+ but not `Sync`, then we'll need to wrap it in something like a `Mutex` and put
+ it in a static.
diff --git a/src/bare-metal/aps/inline-assembly.md b/src/bare-metal/aps/inline-assembly.md
index 0af641fa12d3..31336c418b55 100644
--- a/src/bare-metal/aps/inline-assembly.md
+++ b/src/bare-metal/aps/inline-assembly.md
@@ -1,30 +1,35 @@
# Inline assembly
-Sometimes we need to use assembly to do things that aren't possible with Rust code. For example,
-to make an HVC (hypervisor call) to tell the firmware to power off the system:
+Sometimes we need to use assembly to do things that aren't possible with Rust
+code. For example, to make an HVC (hypervisor call) to tell the firmware to
+power off the system:
```rust,editable,compile_fail
{{#include examples/src/main_psci.rs:main}}
```
-(If you actually want to do this, use the [`smccc`][1] crate which has wrappers for all these functions.)
+(If you actually want to do this, use the [`smccc`][1] crate which has wrappers
+for all these functions.)
-* PSCI is the Arm Power State Coordination Interface, a standard set of functions to manage system
- and CPU power states, among other things. It is implemented by EL3 firmware and hypervisors on
- many systems.
-* The `0 => _` syntax means initialise the register to 0 before running the inline assembly code,
- and ignore its contents afterwards. We need to use `inout` rather than `in` because the call could
- potentially clobber the contents of the registers.
-* This `main` function needs to be `#[no_mangle]` and `extern "C"` because it is called from our
- entry point in `entry.S`.
-* `_x0`–`_x3` are the values of registers `x0`–`x3`, which are conventionally used by the bootloader
- to pass things like a pointer to the device tree. According to the standard aarch64 calling
- convention (which is what `extern "C"` specifies to use), registers `x0`–`x7` are used for the
- first 8 arguments passed to a function, so `entry.S` doesn't need to do anything special except
- make sure it doesn't change these registers.
-* Run the example in QEMU with `make qemu_psci` under `src/bare-metal/aps/examples`.
+- PSCI is the Arm Power State Coordination Interface, a standard set of
+ functions to manage system and CPU power states, among other things. It is
+ implemented by EL3 firmware and hypervisors on many systems.
+- The `0 => _` syntax means initialise the register to 0 before running the
+ inline assembly code, and ignore its contents afterwards. We need to use
+ `inout` rather than `in` because the call could potentially clobber the
+ contents of the registers.
+- This `main` function needs to be `#[no_mangle]` and `extern "C"` because it is
+ called from our entry point in `entry.S`.
+- `_x0`–`_x3` are the values of registers `x0`–`x3`, which are conventionally
+ used by the bootloader to pass things like a pointer to the device tree.
+ According to the standard aarch64 calling convention (which is what
+ `extern "C"` specifies to use), registers `x0`–`x7` are used for the first 8
+ arguments passed to a function, so `entry.S` doesn't need to do anything
+ special except make sure it doesn't change these registers.
+- Run the example in QEMU with `make qemu_psci` under
+ `src/bare-metal/aps/examples`.
diff --git a/src/bare-metal/aps/logging.md b/src/bare-metal/aps/logging.md
index 8a72bab597e2..0d11f62212c0 100644
--- a/src/bare-metal/aps/logging.md
+++ b/src/bare-metal/aps/logging.md
@@ -1,7 +1,7 @@
# Logging
-It would be nice to be able to use the logging macros from the [`log`][1] crate. We can do this by
-implementing the `Log` trait.
+It would be nice to be able to use the logging macros from the [`log`][1] crate.
+We can do this by implementing the `Log` trait.
```rust,editable,compile_fail
{{#include examples/src/logger.rs:main}}
@@ -9,7 +9,8 @@ implementing the `Log` trait.
-* The unwrap in `log` is safe because we initialise `LOGGER` before calling `set_logger`.
+- The unwrap in `log` is safe because we initialise `LOGGER` before calling
+ `set_logger`.
diff --git a/src/bare-metal/aps/logging/using.md b/src/bare-metal/aps/logging/using.md
index a2e150057a54..0d559a2036d8 100644
--- a/src/bare-metal/aps/logging/using.md
+++ b/src/bare-metal/aps/logging/using.md
@@ -8,7 +8,8 @@ We need to initialise the logger before we use it.
-* Note that our panic handler can now log details of panics.
-* Run the example in QEMU with `make qemu_logger` under `src/bare-metal/aps/examples`.
+- Note that our panic handler can now log details of panics.
+- Run the example in QEMU with `make qemu_logger` under
+ `src/bare-metal/aps/examples`.
diff --git a/src/bare-metal/aps/mmio.md b/src/bare-metal/aps/mmio.md
index 4c63731d0db2..47b81df4d7df 100644
--- a/src/bare-metal/aps/mmio.md
+++ b/src/bare-metal/aps/mmio.md
@@ -1,17 +1,21 @@
# Volatile memory access for MMIO
- * Use `pointer::read_volatile` and `pointer::write_volatile`.
- * Never hold a reference.
- * `addr_of!` lets you get fields of structs without creating an intermediate reference.
+- Use `pointer::read_volatile` and `pointer::write_volatile`.
+- Never hold a reference.
+- `addr_of!` lets you get fields of structs without creating an intermediate
+ reference.
- * Volatile access: read or write operations may have side-effects, so prevent the compiler or
- hardware from reordering, duplicating or eliding them.
- * Usually if you write and then read, e.g. via a mutable reference, the compiler may assume that
- the value read is the same as the value just written, and not bother actually reading memory.
- * Some existing crates for volatile access to hardware do hold references, but this is unsound.
- Whenever a reference exist, the compiler may choose to dereference it.
- * Use the `addr_of!` macro to get struct field pointers from a pointer to the struct.
+- Volatile access: read or write operations may have side-effects, so prevent
+ the compiler or hardware from reordering, duplicating or eliding them.
+ - Usually if you write and then read, e.g. via a mutable reference, the
+ compiler may assume that the value read is the same as the value just
+ written, and not bother actually reading memory.
+- Some existing crates for volatile access to hardware do hold references, but
+ this is unsound. Whenever a reference exist, the compiler may choose to
+ dereference it.
+- Use the `addr_of!` macro to get struct field pointers from a pointer to the
+ struct.
diff --git a/src/bare-metal/aps/other-projects.md b/src/bare-metal/aps/other-projects.md
index 6f021790f5ff..9f769559e02d 100644
--- a/src/bare-metal/aps/other-projects.md
+++ b/src/bare-metal/aps/other-projects.md
@@ -1,29 +1,31 @@
# Other projects
- * [oreboot](https://github.com/oreboot/oreboot)
- * "coreboot without the C"
- * Supports x86, aarch64 and RISC-V.
- * Relies on LinuxBoot rather than having many drivers itself.
- * [Rust RaspberryPi OS tutorial](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)
- * Initialisation, UART driver, simple bootloader, JTAG, exception levels, exception handling,
- page tables
- * Some dodginess around cache maintenance and initialisation in Rust, not necessarily a good
- example to copy for production code.
- * [`cargo-call-stack`](https://crates.io/crates/cargo-call-stack)
- * Static analysis to determine maximum stack usage.
+- [oreboot](https://github.com/oreboot/oreboot)
+ - "coreboot without the C"
+ - Supports x86, aarch64 and RISC-V.
+ - Relies on LinuxBoot rather than having many drivers itself.
+- [Rust RaspberryPi OS tutorial](https://github.com/rust-embedded/rust-raspberrypi-OS-tutorials)
+ - Initialisation, UART driver, simple bootloader, JTAG, exception levels,
+ exception handling, page tables
+ - Some dodginess around cache maintenance and initialisation in Rust, not
+ necessarily a good example to copy for production code.
+- [`cargo-call-stack`](https://crates.io/crates/cargo-call-stack)
+ - Static analysis to determine maximum stack usage.
-* The RaspberryPi OS tutorial runs Rust code before the MMU and caches are enabled. This will read
- and write memory (e.g. the stack). However:
- * Without the MMU and cache, unaligned accesses will fault. It builds with `aarch64-unknown-none`
- which sets `+strict-align` to prevent the compiler generating unaligned accesses so it should be
- alright, but this is not necessarily the case in general.
- * If it were running in a VM, this can lead to cache coherency issues. The problem is that the VM
- is accessing memory directly with the cache disabled, while the host has cacheable aliases to the
- same memory. Even if the host doesn't explicitly access the memory, speculative accesses can
- lead to cache fills, and then changes from one or the other will get lost. Again this is alright
- in this particular case (running directly on the hardware with no hypervisor), but isn't a good
- pattern in general.
+- The RaspberryPi OS tutorial runs Rust code before the MMU and caches are
+ enabled. This will read and write memory (e.g. the stack). However:
+ - Without the MMU and cache, unaligned accesses will fault. It builds with
+ `aarch64-unknown-none` which sets `+strict-align` to prevent the compiler
+ generating unaligned accesses so it should be alright, but this is not
+ necessarily the case in general.
+ - If it were running in a VM, this can lead to cache coherency issues. The
+ problem is that the VM is accessing memory directly with the cache disabled,
+ while the host has cacheable aliases to the same memory. Even if the host
+ doesn't explicitly access the memory, speculative accesses can lead to cache
+ fills, and then changes from one or the other will get lost. Again this is
+ alright in this particular case (running directly on the hardware with no
+ hypervisor), but isn't a good pattern in general.
diff --git a/src/bare-metal/aps/uart.md b/src/bare-metal/aps/uart.md
index 9c868bff5acb..4d5ca726e976 100644
--- a/src/bare-metal/aps/uart.md
+++ b/src/bare-metal/aps/uart.md
@@ -8,16 +8,18 @@ The QEMU 'virt' machine has a [PL011][1] UART, so let's write a driver for that.
-* Note that `Uart::new` is unsafe while the other methods are safe. This is because as long as the
- caller of `Uart::new` guarantees that its safety requirements are met (i.e. that there is only
- ever one instance of the driver for a given UART, and nothing else aliasing its address space),
- then it is always safe to call `write_byte` later because we can assume the necessary
+- Note that `Uart::new` is unsafe while the other methods are safe. This is
+ because as long as the caller of `Uart::new` guarantees that its safety
+ requirements are met (i.e. that there is only ever one instance of the driver
+ for a given UART, and nothing else aliasing its address space), then it is
+ always safe to call `write_byte` later because we can assume the necessary
preconditions.
-* We could have done it the other way around (making `new` safe but `write_byte` unsafe), but that
- would be much less convenient to use as every place that calls `write_byte` would need to reason
- about the safety
-* This is a common pattern for writing safe wrappers of unsafe code: moving the burden of proof for
- soundness from a large number of places to a smaller number of places.
+- We could have done it the other way around (making `new` safe but `write_byte`
+ unsafe), but that would be much less convenient to use as every place that
+ calls `write_byte` would need to reason about the safety
+- This is a common pattern for writing safe wrappers of unsafe code: moving the
+ burden of proof for soundness from a large number of places to a smaller
+ number of places.
diff --git a/src/bare-metal/aps/uart/traits.md b/src/bare-metal/aps/uart/traits.md
index 95b5f7499c6e..1f69e9ffa44c 100644
--- a/src/bare-metal/aps/uart/traits.md
+++ b/src/bare-metal/aps/uart/traits.md
@@ -1,6 +1,7 @@
# More traits
-We derived the `Debug` trait. It would be useful to implement a few more traits too.
+We derived the `Debug` trait. It would be useful to implement a few more traits
+too.
```rust,editable,compile_fail
{{#include ../examples/src/pl011_minimal.rs:Traits}}
@@ -8,7 +9,9 @@ We derived the `Debug` trait. It would be useful to implement a few more traits
-* Implementing `Write` lets us use the `write!` and `writeln!` macros with our `Uart` type.
-* Run the example in QEMU with `make qemu_minimal` under `src/bare-metal/aps/examples`.
+- Implementing `Write` lets us use the `write!` and `writeln!` macros with our
+ `Uart` type.
+- Run the example in QEMU with `make qemu_minimal` under
+ `src/bare-metal/aps/examples`.
diff --git a/src/bare-metal/microcontrollers.md b/src/bare-metal/microcontrollers.md
index c41758c89760..a9b1b7e04255 100644
--- a/src/bare-metal/microcontrollers.md
+++ b/src/bare-metal/microcontrollers.md
@@ -1,17 +1,21 @@
# Microcontrollers
-The `cortex_m_rt` crate provides (among other things) a reset handler for Cortex M microcontrollers.
+The `cortex_m_rt` crate provides (among other things) a reset handler for Cortex
+M microcontrollers.
+
+
```rust,editable,compile_fail
{{#include microcontrollers/examples/src/bin/minimal.rs:Example}}
```
-Next we'll look at how to access peripherals, with increasing levels of abstraction.
+Next we'll look at how to access peripherals, with increasing levels of
+abstraction.
-* The `cortex_m_rt::entry` macro requires that the function have type `fn() -> !`, because returning
- to the reset handler doesn't make sense.
-* Run the example with `cargo embed --bin minimal`
+- The `cortex_m_rt::entry` macro requires that the function have type
+ `fn() -> !`, because returning to the reset handler doesn't make sense.
+- Run the example with `cargo embed --bin minimal`
diff --git a/src/bare-metal/microcontrollers/board-support.md b/src/bare-metal/microcontrollers/board-support.md
index 07853ebc3f34..f99745efc62a 100644
--- a/src/bare-metal/microcontrollers/board-support.md
+++ b/src/bare-metal/microcontrollers/board-support.md
@@ -1,18 +1,21 @@
# Board support crates
-Board support crates provide a further level of wrapping for a specific board for convenience.
+Board support crates provide a further level of wrapping for a specific board
+for convenience.
+
+
```rust,editable,compile_fail
{{#include examples/src/bin/board_support.rs:Example}}
```
- * In this case the board support crate is just providing more useful names, and a bit of
- initialisation.
- * The crate may also include drivers for some on-board devices outside of the microcontroller
- itself.
- * `microbit-v2` includes a simple driver for the LED matrix.
+- In this case the board support crate is just providing more useful names, and
+ a bit of initialisation.
+- The crate may also include drivers for some on-board devices outside of the
+ microcontroller itself.
+ - `microbit-v2` includes a simple driver for the LED matrix.
Run the example with:
diff --git a/src/bare-metal/microcontrollers/debugging.md b/src/bare-metal/microcontrollers/debugging.md
index 7753a4b5d883..349e0918482f 100644
--- a/src/bare-metal/microcontrollers/debugging.md
+++ b/src/bare-metal/microcontrollers/debugging.md
@@ -1,7 +1,9 @@
# Debugging
_Embed.toml_:
+
+
```toml
[default.general]
chip = "nrf52833_xxAA"
@@ -11,7 +13,9 @@ enabled = true
```
In one terminal under `src/bare-metal/microcontrollers/examples/`:
+
+
```sh
cargo embed --bin board_support debug
```
@@ -19,20 +23,27 @@ cargo embed --bin board_support debug
In another terminal in the same directory:
On gLinux or Debian:
+
+
```sh
gdb-multiarch target/thumbv7em-none-eabihf/debug/board_support --eval-command="target remote :1337"
```
On MacOS:
+
+
```sh
arm-none-eabi-gdb target/thumbv7em-none-eabihf/debug/board_support --eval-command="target remote :1337"
```
+
In GDB, try running:
+
+
```gdb
b src/bin/board_support.rs:29
b src/bin/board_support.rs:30
diff --git a/src/bare-metal/microcontrollers/embedded-hal.md b/src/bare-metal/microcontrollers/embedded-hal.md
index d1d325e83c52..5e8c3da90de8 100644
--- a/src/bare-metal/microcontrollers/embedded-hal.md
+++ b/src/bare-metal/microcontrollers/embedded-hal.md
@@ -1,23 +1,25 @@
# `embedded-hal`
-The [`embedded-hal`](https://crates.io/crates/embedded-hal) crate provides a number of traits
-covering common microcontroller peripherals.
+The [`embedded-hal`](https://crates.io/crates/embedded-hal) crate provides a
+number of traits covering common microcontroller peripherals.
- * GPIO
- * ADC
- * I2C, SPI, UART, CAN
- * RNG
- * Timers
- * Watchdogs
+- GPIO
+- ADC
+- I2C, SPI, UART, CAN
+- RNG
+- Timers
+- Watchdogs
Other crates then implement
-[drivers](https://github.com/rust-embedded/awesome-embedded-rust#driver-crates) in terms of these
-traits, e.g. an accelerometer driver might need an I2C or SPI bus implementation.
+[drivers](https://github.com/rust-embedded/awesome-embedded-rust#driver-crates)
+in terms of these traits, e.g. an accelerometer driver might need an I2C or SPI
+bus implementation.
- * There are implementations for many microcontrollers, as well as other platforms such as Linux on
-Raspberry Pi.
- * There is work in progress on an `async` version of `embedded-hal`, but it isn't stable yet.
+- There are implementations for many microcontrollers, as well as other
+ platforms such as Linux on Raspberry Pi.
+- There is work in progress on an `async` version of `embedded-hal`, but it
+ isn't stable yet.
diff --git a/src/bare-metal/microcontrollers/hals.md b/src/bare-metal/microcontrollers/hals.md
index 642e0adca3d6..9b9b3d206a87 100644
--- a/src/bare-metal/microcontrollers/hals.md
+++ b/src/bare-metal/microcontrollers/hals.md
@@ -1,8 +1,9 @@
# HAL crates
-[HAL crates](https://github.com/rust-embedded/awesome-embedded-rust#hal-implementation-crates) for
-many microcontrollers provide wrappers around various peripherals. These generally implement traits
-from [`embedded-hal`](https://crates.io/crates/embedded-hal).
+[HAL crates](https://github.com/rust-embedded/awesome-embedded-rust#hal-implementation-crates)
+for many microcontrollers provide wrappers around various peripherals. These
+generally implement traits from
+[`embedded-hal`](https://crates.io/crates/embedded-hal).
```rust,editable,compile_fail
{{#include examples/src/bin/hal.rs:Example}}
@@ -10,9 +11,9 @@ from [`embedded-hal`](https://crates.io/crates/embedded-hal).
- * `set_low` and `set_high` are methods on the `embedded_hal` `OutputPin` trait.
- * HAL crates exist for many Cortex-M and RISC-V devices, including various STM32, GD32, nRF, NXP,
- MSP430, AVR and PIC microcontrollers.
+- `set_low` and `set_high` are methods on the `embedded_hal` `OutputPin` trait.
+- HAL crates exist for many Cortex-M and RISC-V devices, including various
+ STM32, GD32, nRF, NXP, MSP430, AVR and PIC microcontrollers.
Run the example with:
diff --git a/src/bare-metal/microcontrollers/mmio.md b/src/bare-metal/microcontrollers/mmio.md
index 57f37119e702..426083fb91ac 100644
--- a/src/bare-metal/microcontrollers/mmio.md
+++ b/src/bare-metal/microcontrollers/mmio.md
@@ -1,7 +1,7 @@
# Raw MMIO
-Most microcontrollers access peripherals via memory-mapped IO. Let's try turning on an LED on our
-micro:bit:
+Most microcontrollers access peripherals via memory-mapped IO. Let's try turning
+on an LED on our micro:bit:
```rust,editable,compile_fail
{{#include examples/src/bin/mmio.rs:Example}}
@@ -9,7 +9,8 @@ micro:bit:
-* GPIO 0 pin 21 is connected to the first column of the LED matrix, and pin 28 to the first row.
+- GPIO 0 pin 21 is connected to the first column of the LED matrix, and pin 28
+ to the first row.
Run the example with:
diff --git a/src/bare-metal/microcontrollers/other-projects.md b/src/bare-metal/microcontrollers/other-projects.md
index d653c93ee690..8434b02ff298 100644
--- a/src/bare-metal/microcontrollers/other-projects.md
+++ b/src/bare-metal/microcontrollers/other-projects.md
@@ -1,26 +1,29 @@
# Other projects
- * [RTIC](https://rtic.rs/)
- * "Real-Time Interrupt-driven Concurrency"
- * Shared resource management, message passing, task scheduling, timer queue
- * [Embassy](https://embassy.dev/)
- * `async` executors with priorities, timers, networking, USB
- * [TockOS](https://www.tockos.org/documentation/getting-started)
- * Security-focused RTOS with preemptive scheduling and Memory Protection Unit support
- * [Hubris](https://hubris.oxide.computer/)
- * Microkernel RTOS from Oxide Computer Company with memory protection, unprivileged drivers, IPC
- * [Bindings for FreeRTOS](https://github.com/lobaro/FreeRTOS-rust)
- * Some platforms have `std` implementations, e.g.
- [esp-idf](https://esp-rs.github.io/book/overview/using-the-standard-library.html).
+- [RTIC](https://rtic.rs/)
+ - "Real-Time Interrupt-driven Concurrency"
+ - Shared resource management, message passing, task scheduling, timer queue
+- [Embassy](https://embassy.dev/)
+ - `async` executors with priorities, timers, networking, USB
+- [TockOS](https://www.tockos.org/documentation/getting-started)
+ - Security-focused RTOS with preemptive scheduling and Memory Protection Unit
+ support
+- [Hubris](https://hubris.oxide.computer/)
+ - Microkernel RTOS from Oxide Computer Company with memory protection,
+ unprivileged drivers, IPC
+- [Bindings for FreeRTOS](https://github.com/lobaro/FreeRTOS-rust)
+- Some platforms have `std` implementations, e.g.
+ [esp-idf](https://esp-rs.github.io/book/overview/using-the-standard-library.html).
- * RTIC can be considered either an RTOS or a concurrency framework.
- * It doesn't include any HALs.
- * It uses the Cortex-M NVIC (Nested Virtual Interrupt Controller) for scheduling rather than a
- proper kernel.
- * Cortex-M only.
- * Google uses TockOS on the Haven microcontroller for Titan security keys.
- * FreeRTOS is mostly written in C, but there are Rust bindings for writing applications.
+- RTIC can be considered either an RTOS or a concurrency framework.
+ - It doesn't include any HALs.
+ - It uses the Cortex-M NVIC (Nested Virtual Interrupt Controller) for
+ scheduling rather than a proper kernel.
+ - Cortex-M only.
+- Google uses TockOS on the Haven microcontroller for Titan security keys.
+- FreeRTOS is mostly written in C, but there are Rust bindings for writing
+ applications.
diff --git a/src/bare-metal/microcontrollers/pacs.md b/src/bare-metal/microcontrollers/pacs.md
index 86e0b0d7204a..2ecb30f299a0 100644
--- a/src/bare-metal/microcontrollers/pacs.md
+++ b/src/bare-metal/microcontrollers/pacs.md
@@ -1,8 +1,8 @@
# Peripheral Access Crates
-[`svd2rust`](https://crates.io/crates/svd2rust) generates mostly-safe Rust wrappers for
-memory-mapped peripherals from [CMSIS-SVD](https://www.keil.com/pack/doc/CMSIS/SVD/html/index.html)
-files.
+[`svd2rust`](https://crates.io/crates/svd2rust) generates mostly-safe Rust
+wrappers for memory-mapped peripherals from
+[CMSIS-SVD](https://www.keil.com/pack/doc/CMSIS/SVD/html/index.html) files.
```rust,editable,compile_fail
{{#include examples/src/bin/pac.rs:Example}}
@@ -10,15 +10,17 @@ files.
-* SVD (System View Description) files are XML files typically provided by silicon vendors which
- describe the memory map of the device.
- * They are organised by peripheral, register, field and value, with names, descriptions, addresses
- and so on.
- * SVD files are often buggy and incomplete, so there are various projects which patch the
- mistakes, add missing details, and publish the generated crates.
-* `cortex-m-rt` provides the vector table, among other things.
-* If you `cargo install cargo-binutils` then you can run
- `cargo objdump --bin pac -- -d --no-show-raw-insn` to see the resulting binary.
+- SVD (System View Description) files are XML files typically provided by
+ silicon vendors which describe the memory map of the device.
+ - They are organised by peripheral, register, field and value, with names,
+ descriptions, addresses and so on.
+ - SVD files are often buggy and incomplete, so there are various projects
+ which patch the mistakes, add missing details, and publish the generated
+ crates.
+- `cortex-m-rt` provides the vector table, among other things.
+- If you `cargo install cargo-binutils` then you can run
+ `cargo objdump --bin pac -- -d --no-show-raw-insn` to see the resulting
+ binary.
Run the example with:
diff --git a/src/bare-metal/microcontrollers/probe-rs.md b/src/bare-metal/microcontrollers/probe-rs.md
index 1633139489f4..1d9953509e5d 100644
--- a/src/bare-metal/microcontrollers/probe-rs.md
+++ b/src/bare-metal/microcontrollers/probe-rs.md
@@ -1,11 +1,11 @@
# `probe-rs` and `cargo-embed`
-[probe-rs](https://probe.rs/) is a handy toolset for embedded debugging, like OpenOCD but better
-integrated.
+[probe-rs](https://probe.rs/) is a handy toolset for embedded debugging, like
+OpenOCD but better integrated.
-* SWD (Serial Wire Debug) and JTAG via CMSIS-DAP, ST-Link and J-Link probes
-* GDB stub and Microsoft DAP (Debug Adapter Protocol) server
-* Cargo integration
+- SWD (Serial Wire Debug) and JTAG via CMSIS-DAP, ST-Link and J-Link probes
+- GDB stub and Microsoft DAP (Debug Adapter Protocol) server
+- Cargo integration
`cargo-embed` is a cargo subcommand to build and flash binaries, log RTT (Real
Time Transfers) output and connect GDB. It's configured by an `Embed.toml` file
@@ -13,17 +13,22 @@ in your project directory.
-* [CMSIS-DAP](https://arm-software.github.io/CMSIS_5/DAP/html/index.html) is an Arm standard
- protocol over USB for an in-circuit debugger to access the CoreSight Debug Access Port of various
- Arm Cortex processors. It's what the on-board debugger on the BBC micro:bit uses.
-* ST-Link is a range of in-circuit debuggers from ST Microelectronics, J-Link is a range from
- SEGGER.
-* The Debug Access Port is usually either a 5-pin JTAG interface or 2-pin Serial Wire Debug.
-* probe-rs is a library which you can integrate into your own tools if you want to.
-* The [Microsoft Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) lets
- VSCode and other IDEs debug code running on any supported microcontroller.
-* cargo-embed is a binary built using the probe-rs library.
-* RTT (Real Time Transfers) is a mechanism to transfer data between the debug host and the target
- through a number of ringbuffers.
+- [CMSIS-DAP](https://arm-software.github.io/CMSIS_5/DAP/html/index.html) is an
+ Arm standard protocol over USB for an in-circuit debugger to access the
+ CoreSight Debug Access Port of various Arm Cortex processors. It's what the
+ on-board debugger on the BBC micro:bit uses.
+- ST-Link is a range of in-circuit debuggers from ST Microelectronics, J-Link is
+ a range from SEGGER.
+- The Debug Access Port is usually either a 5-pin JTAG interface or 2-pin Serial
+ Wire Debug.
+- probe-rs is a library which you can integrate into your own tools if you want
+ to.
+- The
+ [Microsoft Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
+ lets VSCode and other IDEs debug code running on any supported
+ microcontroller.
+- cargo-embed is a binary built using the probe-rs library.
+- RTT (Real Time Transfers) is a mechanism to transfer data between the debug
+ host and the target through a number of ringbuffers.
diff --git a/src/bare-metal/microcontrollers/type-state.md b/src/bare-metal/microcontrollers/type-state.md
index 5829b171d473..0ed4edf0c214 100644
--- a/src/bare-metal/microcontrollers/type-state.md
+++ b/src/bare-metal/microcontrollers/type-state.md
@@ -6,15 +6,17 @@
- * Pins don't implement `Copy` or `Clone`, so only one instance of each can exist. Once a pin is
- moved out of the port struct nobody else can take it.
- * Changing the configuration of a pin consumes the old pin instance, so you can’t keep use the old
- instance afterwards.
- * The type of a value indicates the state that it is in: e.g. in this case, the configuration state
- of a GPIO pin. This encodes the state machine into the type system, and ensures that you don't
- try to use a pin in a certain way without properly configuring it first. Illegal state
- transitions are caught at compile time.
- * You can call `is_high` on an input pin and `set_high` on an output pin, but not vice-versa.
- * Many HAL crates follow this pattern.
+- Pins don't implement `Copy` or `Clone`, so only one instance of each can
+ exist. Once a pin is moved out of the port struct nobody else can take it.
+- Changing the configuration of a pin consumes the old pin instance, so you
+ can’t keep use the old instance afterwards.
+- The type of a value indicates the state that it is in: e.g. in this case, the
+ configuration state of a GPIO pin. This encodes the state machine into the
+ type system, and ensures that you don't try to use a pin in a certain way
+ without properly configuring it first. Illegal state transitions are caught at
+ compile time.
+- You can call `is_high` on an input pin and `set_high` on an output pin, but
+ not vice-versa.
+- Many HAL crates follow this pattern.
diff --git a/src/bare-metal/minimal.md b/src/bare-metal/minimal.md
index a4e00dd3de39..c257d23f5e8e 100644
--- a/src/bare-metal/minimal.md
+++ b/src/bare-metal/minimal.md
@@ -1,5 +1,7 @@
# A minimal `no_std` program
+
+
```rust,editable,compile_fail
#![no_main]
#![no_std]
@@ -14,13 +16,13 @@ fn panic(_panic: &PanicInfo) -> ! {
-* This will compile to an empty binary.
-* `std` provides a panic handler; without it we must provide our own.
-* It can also be provided by another crate, such as `panic-halt`.
-* Depending on the target, you may need to compile with `panic = "abort"` to avoid an error about
- `eh_personality`.
-* Note that there is no `main` or any other entry point; it's up to you to define your own entry
- point. This will typically involve a linker script and some assembly code to set things up ready
- for Rust code to run.
+- This will compile to an empty binary.
+- `std` provides a panic handler; without it we must provide our own.
+- It can also be provided by another crate, such as `panic-halt`.
+- Depending on the target, you may need to compile with `panic = "abort"` to
+ avoid an error about `eh_personality`.
+- Note that there is no `main` or any other entry point; it's up to you to
+ define your own entry point. This will typically involve a linker script and
+ some assembly code to set things up ready for Rust code to run.
diff --git a/src/bare-metal/no_std.md b/src/bare-metal/no_std.md
index 9ea4d5df86a2..4f984e7f0760 100644
--- a/src/bare-metal/no_std.md
+++ b/src/bare-metal/no_std.md
@@ -3,7 +3,7 @@
| - + `core` | @@ -21,37 +21,37 @@||
|---|---|---|
| -* Slices, `&str`, `CStr` -* `NonZeroU8`... -* `Option`, `Result` -* `Display`, `Debug`, `write!`... -* `Iterator` -* `panic!`, `assert_eq!`... -* `NonNull` and all the usual pointer-related functions -* `Future` and `async`/`await` -* `fence`, `AtomicBool`, `AtomicPtr`, `AtomicU32`... -* `Duration` +- Slices, `&str`, `CStr` +- `NonZeroU8`... +- `Option`, `Result` +- `Display`, `Debug`, `write!`... +- `Iterator` +- `panic!`, `assert_eq!`... +- `NonNull` and all the usual pointer-related functions +- `Future` and `async`/`await` +- `fence`, `AtomicBool`, `AtomicPtr`, `AtomicU32`... +- `Duration` | -* `Box`, `Cow`, `Arc`, `Rc` -* `Vec`, `BinaryHeap`, `BtreeMap`, `LinkedList`, `VecDeque` -* `String`, `CString`, `format!` +- `Box`, `Cow`, `Arc`, `Rc` +- `Vec`, `BinaryHeap`, `BtreeMap`, `LinkedList`, `VecDeque` +- `String`, `CString`, `format!` | -* `Error` -* `HashMap` -* `Mutex`, `Condvar`, `Barrier`, `Once`, `RwLock`, `mpsc` -* `File` and the rest of `fs` -* `println!`, `Read`, `Write`, `Stdin`, `Stdout` and the rest of `io` -* `Path`, `OsString` -* `net` -* `Command`, `Child`, `ExitCode` -* `spawn`, `sleep` and the rest of `thread` -* `SystemTime`, `Instant` +- `Error` +- `HashMap` +- `Mutex`, `Condvar`, `Barrier`, `Once`, `RwLock`, `mpsc` +- `File` and the rest of `fs` +- `println!`, `Read`, `Write`, `Stdin`, `Stdout` and the rest of `io` +- `Path`, `OsString` +- `net` +- `Command`, `Child`, `ExitCode` +- `spawn`, `sleep` and the rest of `thread` +- `SystemTime`, `Instant` |
