# Rust Training Course, April 27th - May 7th
This document serves as a living document for everyone to share information, links or note down questions during the Rust course.

You can edit it! (using [Markdown syntax](https://www.markdownguide.org/basic-syntax/))
Feel free to liberally use the "Questions" section at the bottom to ask general questions or post code snippets you want to discuss.

## Topic list

The course will cover the subjects listed in the [core course](https://github.com/ferrous-systems/teaching-material/#core-topics), along with some subjects decided as a group.

## Dates & Access

**Conferencing link has been provided by the separate calendar invite.**

Apr. 27th-May 4th: Rust basics
May 5th - 6th: Embedded Workshops
May 7th: TBD

## Time

All times are in CEST (Berlin), check [https://everytimezone.com/](https://everytimezone.com/s/dd8cb638) for your offset.

| Start Time | End Time | Contents |
| :--- | :--- | :--- |
| 07:45 AM | 08:00 AM | Room open, trainer arrives and is available for questions |
| 08:00 AM | 11:15 AM | Training, breaks, organization TBD |
| 11:15 AM | 11:30 AM | Open Q&A, unsorted things that came up during the day |

We will go through the detailed schedule and planning during the first day, when we have a chance to collect personal interests.

If someone needs to leave early on a day, please let us know beforehand, this e.g. allows us to reorganise Q&A subjects according to their interests.

## Preparation

Please prepare the following questions:

* What do you want to use Rust for?
* Which are the questions that you've always been interested in?
* If you already worked with Rust: what was the hardest part for you?
* With which of the following (rough) language families do you identify most?
- C/C++
- Objective-C/Swift
- Haskell/ML
- Ruby/Python/Perl/Java

You will need to install Rust through https://rustup.rs/. I can highly recommend doing this on Windows, as installation of the Windows SDK may take some time.

## [Slides](https://ferrous-systems.github.io/teaching-material/)

we covered:

### day 1
- [overview](https://ferrous-systems.github.io/teaching-material/overview.html)
- [toolchain](https://ferrous-systems.github.io/teaching-material/installation.html)
- [basic types](https://ferrous-systems.github.io/teaching-material/basic-types.html)
- [compound types](https://ferrous-systems.github.io/teaching-material/compound-types.html)
- beginning of [control flow](https://ferrous-systems.github.io/teaching-material/control-flow.html) (we finished with match and enums)

### day 2

- fill in the blanks [`match` exercise](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=57d751ef529b2da809ceb48b3028bc6c)
- [sample solution](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=e24c725984c5a8714452d7e46959e82d)
- [Simple Generics](https://ferrous-systems.github.io/teaching-material/generics-basics.html#/)
- [Implementation and Traits](https://ferrous-systems.github.io/teaching-material/traits.html#/)
- Rest of [Control Flow](https://ferrous-systems.github.io/teaching-material/control-flow.html#/) – Starting at Result and Option
- Exercise: fizzbuzz
- [Ownership & Borrowing](https://ferrous-systems.github.io/teaching-material/ownership-borrowing-in-brief.html#/)

### day 3

- [Durable file Exercise](https://ferrous-systems.github.io/teaching-material/assignments/durable-file.html)
- [Error Handling](https://ferrous-systems.github.io/teaching-material/error-handling.html#/)

## day 4

- [Lifetimes](https://ferrous-systems.github.io/teaching-material/lifetimes#/)
- [Strings](https://ferrous-systems.github.io/teaching-material/strings.html#/)
- [Calculator Exercise](https://ferrous-systems.github.io/teaching-material/assignments/calc.html)

## day 5

- turning calculator into a module
- [Documentation](https://ferrous-systems.github.io/teaching-material/documentation.html#/)
- [docs.rs](https://github.com/rust-lang/docs.rs)
- [doctests](https://doc.rust-lang.org/rustdoc/documentation-tests.html)
- FFI
- [cbindgen](https://github.com/eqrion/cbindgen) and [bindgen](
https://rust-lang.github.io/rust-bindgen/)

## day 6

- [Beginner embedded](https://embedded-trainings.ferrous-systems.com/beginner-workbook.html)

## day 7

- [Advanced Embedded](https://embedded-trainings.ferrous-systems.com/advanced-workbook.html)

// Marker Traits

// Safely transfer data between threads
trait Send {}

// Safely share data between threads
trait Sync {}

// In Embedded Rust, we model Interrups/ISRs as separate threads

// access is ALWAYS unsafe in Rust
static mut FLAG: bool = true;

// "Inner mutability"
static MUTEX_FLAG: Mutex<bool> = Mutex::new(false);

- [rtic](http://rtic.rs)
- [Debuggers](https://ferrous-systems.com/blog/gdb-and-defmt/)

## day 8
- 👀 Topic Requests!

## offline questions
TODO James/Lotte: Answer these via e-mail if we didn't get to cover them in the training

- how does compiler get to know the cacheable attribute of memory/register regions (configured through mpu for example)?

## Material

[Slides](https://ferrous-systems.github.io/teaching-material/)
[The Rust Book](https://doc.rust-lang.org/book/)
[The Embedded Rust Book](https://docs.rust-embedded.org/book/)
([Asynchronous programming with async std](https://book.async.rs/) - not necessary, but we might cover some subjects)
[Awesome Rust Streaming](https://github.com/jamesmunns/awesome-rust-streaming)
[Awesome Rust Mentors](https://github.com/RustBeginners/awesome-rust-mentors)
[Rust Cheat sheet](https://cheats.rs/)
[Implementing Vec](https://doc.rust-lang.org/nomicon/vec.html)
[Embedded Rust WG](https://github.com/rust-embedded/wg)

## Topic Requests

- send/sync
- Will you be covering floating point exception handling (INF, NAN, subs, etc.)?
- serialization/deserialization (dig into serde)?
- composition vs. inheritance
- trait inheritance
- looks like there no inheritance with Rust, what are the alternatives?
~~- make sure we cover lifetimes!~~
- how do we test `close()` for the DurableFile exercise
- Svd2rust
- DMA
- Serialization

## TO REVISIT

- How does RUST handle cast between "integer" and floats.
- TODO: talk about this when we talk about `into()` and `from()` casting; dig up issue that changed this
- Somewhat off topic, but it seems Rust deliberately wouldn't support something like 8086/80286 where there are multiple sizes of pointers intermingled?
- Note for james: find blog post for this
- James: talk slides on serde >> repr optimizations
- James: double-check sequence point assumptions
- James: Submit a bug for this error message:

note: enum defined here, with 2 type parameters: `T`, `E`
   --> C:\Users\pbbudny\.rustup\toolchains\stable-x86_64-pc-windows-msvc\lib/rustlib/src/rust\library\core\src\result.rs:241:10
    |
241 | pub enum Result<T, E> {
    |          ^^^^^^ -  -
help: use angle brackets to add missing type arguments
    |
17  |     pub fn close(mut self) -> Result<T, E><> {
    |                                     ^^^^^^

- Grammar problems on https://ferrous-systems.github.io/teaching-material/ownership-borrowing-in-brief.html#/_working_with_moves_explicit_clone
- @James: FYI, I think the problem you had in that one example with `f32` is that `f32` can only accurately represent integer values up to +/- 2^24. Any larger values will be rounded. (https://en.wikipedia.org/wiki/Single-precision_floating-point_format#Precision_limitations_on_integer_values) Hence why `f32` implements `From` for `i8`, `u8`, `i16`, and `u16` but nothing larger. I got it to work using `f64`, which *does* implement `From<i32>` and `From<u32>`, although you then have to also cast the `self` values to `f64` as well.
- James: Here's my recursive struct that you thought wouldn't work :-) https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=0bcbd30db50e07f792cec5a5f64df580

## Questions

This is a place to note down questions if you don't want to disturb others.

- In the 'Modularization' loop sample code snippet in [Exercise: calculator](https://ferrous-systems.github.io/teaching-material/assignments/calc.html) the check should be ```if n_bytes_read == 1``` to break when enter is pressed.
- TODO (lotte): open new issue in training material repo for this

## Playground collection

Playgrounds can be created at [The playground!](https://play.rust-lang.org).

## Exercises

> Shared information around exercises will be placed here.

* James' Calc solutions:
* [Work in progress](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=460238b886ab487b273efb444d0e3b9e)
* [final form on day 5](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=c5fb191ff5ddcac13133ec72f7911a90)

## Useful tools

[Godbolt compiler explorer](https://rust.godbolt.org/)

## Code examples

> This is a place to collect interesting code snippets.

## Useful crates

[log](https://crates.io/crates/log)
[tracing](https://crates.io/crates/tracing)
[criterion](https://crates.io/crates/criterion)
[immutable datatypes](https://crates.io/crates/im)
[serde](https://crates.io/crates/serde)

## General notes

> This is a place to collect notes that don't fit anywhere else.

# Friday Schedule

1. Send and Sync (threading) +5
* 30 min quick tour +!
* 60 min w/ exercises
1. Finish Advanced Training
* 30 min quick tour +6
* 60 min w/ exercises

18:35-40

1. Heap and Collection and stdlib Types +6
* 30 min tour, with Q&A

19:45

1. Deep dive into more embedded libraries +4
1. Composition vs Inheritance +4
* Note: We covered this a bit w/ DurableFile
1. FFI (wrt FreeRTOS, etc) +4

20:30

3. Deep dive into generally used libraries +2
4. Knurling Embedded Tools: +1
* 10-15m demo
* 15-30m w/exercises +1
5. Debuggers
1. Covering Floating Point Exception Handling -4
1. svd2rust: -4
* Did we cover enough today?
1. Rust on new platforms -1
* Ask Scot for that recording