README.md



Are We Embedded Yet

D7018E - Special Studies in Embedded Systems
Disclaimer: This document is in beta state!!!!! Just to give a hint how the course will look like.
The course will be given as a self study course with a set of introductional seminars and accompanying mandatory assignments, followed by a larger assignment (project). The project can be carried out individually or in groups depending on size. Grading will be individual, based on agreed requirements between the student and the teacher, showing understanding and abilities regarding:


The Rust ecosystem. ecosystem
Rustup (stable vs nightly), crates and toml files, cargo, rustc, llvm, gdb/lldb (and additional tooling rls, rustfmt, racer, xargo etc.) The Rust core and standard library. Building, debugging/testing, documenting and publishing Rust applications and libraries.


Simple applications in Rust
Primitive types, tupels, structs, enums, etc. Flow control and functions. Macro usage.


Rust features
Generics and polymorphism. Closures (and higher order functions). Iterators. Traits, definitions and implementations (derived and explicit). Marker traits. Type bounds.


The Rust Memory Model
Theoretical underpinning, as well as an impact on both memory safety and code generation. Exterior (inherited) and interior mutability (Cell). Move vs. copy semantics, relation to Clone and Copy traits. Lifetimes and scoping. Static lifetimes, and the relation to the Sync trait.


Memory Safe Concurrency
UnsafeCell, and synchronization in the RTFM model. Requirements for Stack Resource Policy (SRP) based single-core scheduling.


Macros
Macro_rules/matching and expansion. Procedural macros (macros 2.0). Overview of the Rust RTFM implementation.


Building and debugging embedded code in Rust
Hardware abstractions using svd2rust (autogenerated from vendor-provided SVD specifications). Compiling using xargo. Setting up openocd and gdb.


Pre-processing
Custom build.rs build scripts, and the RTFM Concurrent Reactive Component model.


Course Format
Please fill out the doodle so we can arrange for a first scheduled seminar. We will use telegram telegram in order to confirm the preferred date. On the first seminar, we will schedule 10 sessions for covering the above topics.
Each topic will be accompanied by a set of small illustrative examples and assignments that each student should master (learning goals). On the following session, each student should prepare to discuss and demonstrate their solutions.
Lectures and assignments will be covered over a 4 week period, leaving time for a larger assignment/project.
Each project should be reported in terms of a git Rust crate, with sufficient documentation (readme.md) to build, and recreate the result.
There will be two presentation rounds (at end of LP2 and LP3). Students taking (too many other) courses during LP2 may choose to present their project at end of LP3 (instead of LP2). Presentations will be oral, where the student(s), will present and demonstrate their work.
Projects should be related to embedded programming, either on the target side (some application using the RTFM-core or CRC model), or on the host side, communicating with an embedded target running Rust RTFM. E.g., two groups can work together with building a system, e.g., with back-end processing of data collected by the embedded system, or by providing a front-end to the embedded system. Alternatively, host side project could relate the development of the RTFM-core/ RTFM-CRC frameworks or related tools (e.g. LLWM-KLEE as a backend for analysis of Rust code).

Resources
Students will carry out the assignments on their personal laptops (in case you don't have a working laptop we will try to lend you one). Tools used are available for Linux and OSX, but with a bit of trickery windows based installations should be possible (but you are on your own here). In case you don't run OSX/Linux native, virtual box or VMware is possible, though debugging of target MCUs are feasible it is a bit more tricky.
Embedded targets STM32F401RE/411RE (Nucleo-64) will be made available to all students. You will need to get a mini-USB cable yourselves. If you prefer to work with some other ARM Cortex M processor, let us know and we will have a look at available support.
Teaching material will be made available through git (this project), build and refined throughout the course.
We encourage all sorts of collaborations in between the students. Rust is not the easiest language to learn, and we will cover a lot of ground. Use the seminars to try to get as much as possible by being well prepared in order to succeed. We will use telegram as the main means of communication and support from teachers as well as other fellow students, (this way information will reach everyone, keeping support as efficient as possible).

Course in detail
Seminars


Welcome.


Preparation
Please bring your laptop, and we will install the Rust tools required in order to compile and run your first application.


Topic
About the course. Scheduling further seminars. Introduction to the Rust ecosystem, and basics of Rust programming.
We will cover the Rust book Rustbook Second Edition sections


1 - Introduction,

2 - Guessing Game Tutorial, and

3 - Common Programming Concepts.


Assignment 1
Extend the guessing game application such to give an error message on ill-formatted input, (use the Result::Err type). Add a counter to the number of tries and write the number of tries for each iteration and on "winning".
Make a GitHub account (if you don't have it). Make a GitHub project with your code, along with a README.md for usage instructions.
Prepare to present your development for the next seminar.


Basic Programming


Preparation
Solve and be prepared to present Assignment 1.


Assessment
We will in the class install, test and comment on one of Your solutions. That is, make sure your crate on git actually works, and that the accompanying readme.md is sufficient for your fellow students in order to recreate the result.
Later in the course, you will assess each others assignments by creating an issue to their development. More on that later.


Topic
Using the Rust ownership model.
Data structures, structs, enums, String (relation to slices) etc. Containers, Vec,  and HashSets/Maps. Iterators. Using the Rust module system. Handling errors.
We will cover the Rust book Rustbook Second Edition sections


4 - Understanding Ownership,


5 - Using Structs to Structure Related Data,


6 - Enums and Pattern Matchings,


7 - Modules,


8 - Common Collections, and


9 - Error Handling.


Assignment 2
a. Break out the line input into a function returning a Result<Ok<u32>>, Err<String>>. In case of a parsing error prepend the Err<String> with the text "in parsing u32, ".
b. Extend the guessing game with a tuple holding (u32, String), store each input (counter, guess) in a vector. Iterate (for) to print the history at exiting. You may solve this in many ways (perhaps your first attempt would be a C like approach), however make use of Iterators in Rust (they will do the indexing for you).
c. Change the program so that it prints the history twice.
d. Change the program so that it prints only the last 3 entries in backwards order (the last entry first). If winning with less than 3 entries, print all (still in backwards order). Use iterators (not C-like indexing).
e. Instead of vector use a 'HashMap', with a key u32 and a value String. Again iterate (for) to print all entries at exiting. (Explain the result.)
f. Optional, find a way to print the last 3 entries of the HashMap (output similar to d).
Make new branches (2a, 2b, ..., 2f) with your solutions, along with a README.md for usage instructions, and expected behavior.
During development you may want to limit the number of tries so you can test without having to bother with answering correctly (the game gets boring after a while.)
Prepare to present your development for the next seminar.


The Rust Memory Model Revisited


Preparation
Finish Assignment 2.


Topic Memory
In-depth discussion of underlying theory, linear types (relation to functional programming). The Affine type system of Rust, requirements on the programmer, and guarantees offered by the compiler. Lifetimes, of stack allocated and global variables. Relation to C++ unique pointers.


Assignment
a. Recall the D0013E course lab2/4, where you decrypted a message in assembler (lab2) and C (lab 4). Now, let's re-implement the lab in Rust (base your development on group number 1's lab assignment).
You have to be careful about the signed/unsigned operations and use wrapping arithmetics to avoid panics due to unsigned carry and signed overflow.
Use borrowed array slices as arguments to decode.
The seed, abc,coded and plain should be stack allocated. The decoded string should be printed when decryption is finished.
b. Make the seed, abc,coded and plain static (heap) allocated (i.e., as global varibles). Accessing those will require some unsafe code. (Keep the unsafe blocks as local as possible.)
c. Safety analysis. Provoke the implementation, by omitting the '\0' (null termination). Observe the result and motivate the behavior in terms of your understanding of the Rust memory model. Under which circumstances do you consider 3a and 3b to have same/different memory safety.
Update your git with two new branches (3a, 3b), and update the documentation to cover usage and analysis (3c).


Cortex-M, are we embedded yet


Preparation
Finish assignment 3. Bring a USB mini cable, and/or your Cortex M dev board of choice. We will provide Nucleo 64s (STM32f401re/STM32f411re if you do not have a board.)


Topic
Embedded programming in Rust.


xargo for building non-std (bare metal) systems


[cortex-m-quickstart]


[cortex-m]


[bluepill/nucleo] crates


Building and debugging your first application.


Assignment
a. Backport assignment 3b to your chosen target. Use semihosting in order to write the resulting string to the host. You may need to use --release for decoding the long (coded) message, as being deeply recursive unoptimized code may run out of stack memory.
b. Discuss from a memory safety perspective the outcome.
c. Compare for the short message (abc), the number of cycles required for decode in debug (standard) vs. --release. As a comparison my straightforword C implementation took 2200 cycles in best optimized mode using gcc (-o3), while my (translation) to Rust code took 1780 cycles (--release). (Both executed on a bluepill board at 8MHz without (flash) memory wait states).
Make a new git for your embedded development. Make three branches (3a, 3b, 3c) with updated documentation according to the above.


Advanced Rust Concepts


Preparation
Be prepared to present the progress on assignment 3.


Topic
Advanced Rust features, trait system and closures.


10 - Generic Types, Traits, and Lifetimes, and

13 - Functional Language Features in Rust.


Assignment
Continue working on assignment 3.


Memory Safe Concurrency


Preparation

Finish lab 3 and be prepared to show your solution.


Topic


UnsafeCell, and synchronization in the RTFM model.


Requirements for Stack Resource Policy (SRP) based single-core scheduling.


cortex-m-rtfm The RTFM-core (task and resource model) in Rust for the Cortex-M family


svd2rust Generating


Assignment 4
Implement a simple system with two tasks

a periodic task executing each 10ms, that blinks the onboard LED, and
USART task receiving commands (pause, start, period)
a shared resource (data structure) protecting the command and period

Make a new git with the development and documentation.


Macros


Preparation
Be prepared to present the progress on assignment 4.


Topic
We will cover the implementation of the RTFM-core crate.
Special focus to macro_rules and procedural macros.


Concurrent Reactive Objects


Preparation
Be prepared to present assignment 4.


Topic
A component model for reactive real-time programming.
We will cover the programming model and the implementation, including the build.rs, parsing of model files and generation of Rust code.


Assignment 5

port the assignment 4 to the RTFM-CRC model.

Make a new git for the development and documentation.


Presentation of project ideas


Preparation
Be prepared to present progress of assignment 5.


Topic
Discussion of projects


Assignment
Write a project specification including individual grading assessment criteria.


Wrap-up


Preparation

Be prepared to present assignment 5.
Be prepared to present your project.