Compare revisions

Are We Embedded Yet

=====================

# 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 assigmnent (project). The project can be carried out individually or in groups dependent on size. Grading will be individual, based on agreed requirements between the student and the teacher, showing understanding and abilities regarding:

The course will be given as a self study course with a set of introduction 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:

1. The Rust ecosystem.

1. The Rust ecosystem. [ecosystem](doc/Ecosystem.md)

    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, bebugging/testing, documenting and publishing Rust applications and libraries.

    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.

2. Simple applications in Rust

    Prmitive types, tupels, structs, enums, etc. Flow control and functions. Macro usage.

    Primitive types, tupels, structs, enums, etc. Flow control and functions. Macro usage.

3. Rust features

4. The Rust Memory Model

    Theoretical underpinning, as well as impact to both memory safatey 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.

    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.

6. Memory Safe Concurrency

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

    Hardware abstractions using svd2rust (auto-generated from vendor-provided SVD specifications). Compiling using xargo. Setting up openocd and gdb.

9. Pre-processing

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

## Course Format

Please fill out the [doodle](http://doodle.com) so we can arrange for a first scheduled seminar. We will use telegram [telegram](http://telegram.com) in order to confirm the preferred date. On the first seminar we will schedule 10 sessions for covering the above topics.

Please fill out the [doodle](http://doodle.com) so we can arrange for a first scheduled seminar. We will use telegram [telegram](http://telegram.com) 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 illustartive examples and assigments that each student should master (learning goals). On the following session, each student should prepare to discuss and demonstrate their solutions.

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 assigments will be covered over a 4 week period, leaving time for a larger assignment/project. 

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 proividing a front-end to the embedded system. Alternatively, host side project could relate the develpment of the RTFM-core/ RTFM-CRC frameworks or related tools (e.g. LLWM-KLEE as a backend for analysis of Rust code).

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. LLVM-KLEE as a back-end 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.

Students will carry out the assignemnts 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 wmware is possible, though debugging of target MCUs are feasible it is a bit more tricky. 

Embedded targets STM32F401RE  (nucleo) will be made available to all students. You will need to get an 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.

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 beig well prepared in order to succeed. We will use telegram as the main means of communictation and support from teachers as well as other fellow students, (this way information will reach everyone, keeping support as efficient as possible).

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

1. 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](doc/Ecosystem.md), and basics of Rust programming.

    We will cover the Rust book [Rustbook Second Edition](https://doc.rust-lang.org/book/second-edition.html) sections 

        We will cover the Rust book [Rustbook Second Edition](https://doc.rust-lang.org/book/second-edition/) sections

        * [1 - Introduction](https://doc.rust-lang.org/book/second-edition/ch01-00-introduction.html),

        * [2 - Guessing Game Tutorial](https://doc.rust-lang.org/book/second-edition/ch02-00-guessing-game-tutorial.html), and

        * [3 - Common Programming Concepts](https://doc.rust-lang.org/book/second-edition/ch03-00-common-programming-concepts.html).

    * Assignment 1

    Extend the guessing game application such to give an error message on ill formated input,(use the Restult::Err type). Add a counter to the number of tries and write the number of tries for each iteration and on "winning".

        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 whith your code, along with a README.md for usage instructions.

        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.

2. Basic Programming

* Preparetion

    * 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](https://doc.rust-lang.org/book/second-edition.html) sections 

        We will cover the Rust book [Rustbook Second Edition](https://doc.rust-lang.org/book/second-edition/) sections

        * [4 - Understanding Ownership](https://doc.rust-lang.org/book/second-edition/ch04-00-understanding-ownership.html),

        * [5 - Using Structs to Structure Related Data](https://doc.rust-lang.org/book/second-edition/ch05-00-structs.html),

        * [8 - Common Collections](https://doc.rust-lang.org/book/second-edition/ch08-00-common-collections.html), and

        * [9 - Error Handling](https://doc.rust-lang.org/book/second-edition/ch09-00-error-handling.html).

    * 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 `Iterator`s in Rust (they will do the indexing for you).

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

        c. Change the program so that it prints the history twice.

    b. Instead of vector use a 'HashMap', with a key `u32` and a value `String`. Again iterate (`for`) to print the history at exiting. (Explain the result.)

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

    c. 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, "`.

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

    d. Optional, find a way to print the `HashMap` in a sorted way. 

        f. Optional, find a way to print the last 3 entries of the `HashMap` (output similar to d).

    Make three new branches (`2a, 2b, 2c`) whith your code, along with a README.md for usage instructions, and expected behavior.

        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.

3. The Rust Memory Model Revisited

    * Preparation

        Finish Assignment 2.

    * Topic [Memory](doc/Memory.md)

* Topic

    In deapth 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`.

        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 3

* Assignment

    a. Recall the D0013E course lab2/4, where you decrypted an 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](www.sm.luth.se/csee/courses/smd/D0013E/labs/lab1underlag/grupp_01.lab1_underlag.s ) lab 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](http://www.sm.luth.se/csee/courses/smd/D0013E/labs/lab1underlag/grupp_01.lab1_underlag.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*.

        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` heap allocated. Accessing those will require some `unsafe` code. (Keep the unsafe blocks as local as possible.)

        b. Make the `seed`, `abc`,`coded` and `plain` static (heap) allocated (i.e., as global variables). 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 termintation). Observe the result and motivate the behavior in terms of your understanding of the Rust memory model. Under which circumpstances do you consider 3a and 3b to have same/different memory safety.

        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 docmentation to cover usage and analysis (`3c`).

        Update your git with two new branches (`3a, 3b`), and update the documentation to cover usage and analysis (`3c`).

4. Cortex-M, are we embedded yet

    * Preparation

* Prepration

    Finish assignment 3. Bring a USB mini cable.

        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. 

        Embedded programming in Rust. Check this [document](doc/Quickstart.md)

        * xargo for building non-`std` (bare metal) systems

    * [cortex-m-quickstart]

    * [cortex-m]

    * ([bluepill/nucleo] crates)

        * `cortex-m-quickstart`, project template

        * `cortex-m`, crate common to all Cortex-M devices

        * `stm32f103xx` and `stm32f40x`, device crates

        * `blue-pill` and `nucleo` board support crates

        * Building and debugging your first application.

    * Assignment 4

* Assignment

    a. Backport assignment `3b` to your choosen 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.

        a. Backport assignment `3b` to your chosen target. Use semi-hosting 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 `--dev` vs. `--release`. As a comparison my straightforword C implementation took 2200 cycles in best optimized mode using `gcc` (-o3), while my (transation) to Rust code took 1780 cycles. (Both executed on a bluepill board at 8MHz with flash memory wait states).

        c. Compare for the short message (`abc`), the number of cycles required for `decode` in debug (standard) vs. `--release`. As a comparison my straightforward 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.

        Make a new git for your embedded development. Make three branches (`4a, 4b, 4c`) with updated documentation according to the above.

5. Advanced Rust Concepts

    * Preparation

* Prepration

    Bring a USB mini cable and your dev board. Be prepared to present the progress on assignment 3.

        Be prepared to present the progress on assignment 4.

    * Topic

        Advanced Rust features, trait system and closures.

        * [10 - Generic Types, Traits, and Lifetimes](https://doc.rust-lang.org/book/second-edition/ch10-00-generics.html), and

        * [13 - Functional Language Features in Rust](https://doc.rust-lang.org/book/second-edition/ch13-00-functional-features.html).

    * Assignment

    Continue working on assignment 3.

6. Memory Safe Concrreny

        Continue working on assignment 4.

6. Memory Safe Concurrency

    * Preparation

    * Finish lab 3 and be prepared to show your solution.

        * Finish assignment 4 and be prepared to show your solution.

    * Topic

        * UnsafeCell, and synchronization in the RTFM model.

        * [cortex-m-rtfm](https://github.com/japaric/cortex-m-rtfm) The RTFM-core (task and resource model) in Rust for the Cortex-M family

        * [svd2rust](https://github.com/japaric/svd2rust) Generating

    * Assignment 5

* Assignment

        Implement a simple system with 3 tasks

    Implement a simple system with two tasks

        * A periodic task executing each Xms (free of accumulated drift, and with minimal jitter), that blinks the on-board LED, and

        * A USART task receiving commands (pause, start, period 1-1000ms), received commands should be parsed and corresponding responses generated and sent over the USART. (Come up with a nice and simple user interface.)

        * A a logging task, run each second (period 1s), that prints statistics of CPU usage over the ITM port

        * Idle should gather statics on sleep/up time, (there is a sleep counter in the cortex core) 

        * Use shared resources (data structures) to ensure race free execution

    * a perodic 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

        You may use the core systic timer (relative) and the dwt cycle counter (absolute) in combination to achieve drift free timing. Alternative you look into the stm32f4xx timer peripheral. There is a support crate for the [STM32F3DISCOVERY](https://github.com/japaric/f3) board. Peripherals are similar so you may "borrow" code from there.

        Make a new git with the development and documentation.

7. Macros

        Optional:

        Find a way to measure the power consumption. A possible solution is to power the board externally and use a power cube with current measuring capability. Alternative use an external power source with known charge (e.g., a "capacitor"), and measure the discharge time (start and residue charge at brown-out voltage), at least a precise relative measure is possible to obtain. 

* Preparation

        Operation without being connected to the USB port: in this case the serial IO and ITM needs to be connected externally (e.g., using some ftdi serial-USB).

    Be prepared to present the progress on assignment 4.

        Super optional:

        Try to minimize power consumption while maintaining desired operation. Lowering supply voltage and using aggressive power modes of the processor might be applied. (Not sure how USART/ITM communication can be made possible at sub 3.3v voltages. Also you have to make sure not to source the board over the communication interfaces.)

* Topic

    We will cover implementation of the RTFM-core crate.

    Special focus to `macro_rules` and `procedural macros`.

8. Concurrent Reactive Objects

7. Macros and Projects (Monday Nov. 20th)

    * Preparation 

    Be prepared to present assignment 4.

        Be prepared to present the progress on assignment 5.

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

        - We will cover the implementation of the rtfm-core and the cortex-m-rtfm crates. For details see [RTFM](doc/RTFM.md).

* Assignment

    * port the assignment 4 to the RTFM-CRC model.

    Make a new git for the development and documentation.

9.  Presentation of project ideas

* Preparation

          Special focus to `macro_rules` and `procedural macros`.

    Be prepared to present progress of assignmont 5.

        - RTFM-CRC A component model for reactive real-time programming.

* Topic

          We will cover the programming model and the implementation, including the `build.rs`, parsing of model files and generation of Rust code.

    Discussion of projects

        - Discussion of project ideas

    * Assignment

        Write a project specification including individual grading assessment criteria.

    Write a project specicification including individual grading assessment critera.

10. Wrapup 

8. Wrap-up (Monday Dec. 4th)

    * Preparation

        * Be prepared to present assignment 5.

    * Be prepared to present your project.

 <!-- It's very easy to make some words **bold** and other words *italic* with Markdown. You can even [link to Google!](http://google.com)  -->

        * Be prepared to present your project, 10 minutes per project.

        * A good idea is to prepare a git for the project with a `README.md` and use that as supporting material for your presentation. Its advicable to have a section (or in a doc sub folder) where you collect references to the material you will use, i.e., links to data sheets, links to other related crates and projects of importance to your project. 

        This type of reference section will be largely helpful to both you (during the project and afterwards maintaining it, but also to other users and people interested in your work). Moreover, from a "course" perspective it shows that you have done the necessary background studies BEFORE you "hack away". Of corse this will be a living document, updated throughout the project, but its a very good thing to start out NOW, then it can be used for your 10 minutes of fame!

* [cargo-update](https://crates.io/crates/cargo-update), cargo sub-command to manage crate updates 

* [xargo](https://crates.io/crates/xargo) Systoot manager to build for non-`std` targets

Various other Rust tools you might find useful

* [rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code

The Rust ecosystem also provides support to program development, in terms of external `crates` for code completion formatting and formatting

* [racer](https://crates.io/crates/racer/), Code completion for Rustbuild system and package/crate manager 

* [rustfmt](https://crates.io/crates/rustfmt), Tool to find and fix Rust formatting issues 

* [itm](https://crates.io/crates/itm) Tool to parse and dump ITM packets

* add here your favorite crates

* [rls-preview](https://github.com/rust-lang-nursery/rls), Rust Language Server (RLS). RLS is a server that runs in the background, providing IDEs, editors, and other tools with information about Rust programs. The `rls-preview` is in alpha state, meaning that it's not guaranteed to compile/work. (You may check under build/passing, the latest changes that passed compilation.)

Rust support for various IDEs and editors 

* [rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code, based on the `rls-preview`. This is the reference implementation for `rls` support (currently in alpha/preview state).

* [rustdt](http://rustdt.github.io/), Rust support for the Eclipse platform (currently not further maintained)

* Atom, Sublime, Code::Blocks support is also available

Other tools and packages 

* [rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust), Rust support for Visual Studio Code

* [rustdt](http://rustdt.github.io/), Rust support for the Eclipse platform

* add here your favorite tools supproting Rust development

Other tools that come in handy for embedded development

* [itm](https://crates.io/crates/itm) Tool to parse and dump ITM packets

* add here your favorite tools supporting Rust development

# Installation

We suggest a linux or OSX development environment, though Rust related tools are also available under Windows. Install  [rustup](https://www.rustup.rs/), Rust tool-chain manager using the link, and go from there.

We suggest a Linux or OSX development environment, though Rust related tools are also available on Windows. Install  [rustup](https://www.rustup.rs/), Rust tool-chain manager using the link, and go from there.

# Rustup

The [rustup](https://www.rustup.rs/), tool manager allows you to manage multiple tool chain installations. Nightly tool chains allow for the development of libraries and applations including `unsafe` code (which will be necessary for the later excercises). For some tools to work (rls/rustfmt) you need to install the Rust sources. By default your Rust related tools will be stored in `~/.rustup`.

The [rustup](https://www.rustup.rs/), tool manager allows you to manage multiple tool chain installations. Rust is distributed in three channels (`stable`, `beta` and `nightly`). You may set the default toolchain:

```

rustup default nightly-2018-01-10-x86_64-unknown-linux-gnu 

```

and get information on the status of `rustup`

```

rustup show

```

Nightly tool chains allow for the development of libraries and applications including `unsafe` code using features not available on the `stable channel` (which will be necessary for the later exercises). For some tools to work (`rls/rustfmt`), you need to install additional components. For this to work, you should use a nightly toolchain for which all tools and components work (currently `nightly-2018-01-10` is the latest). Here is an example:

```

rustup default nightly-2018-01-10

rustup component add rls-preview

rustup component add rust-analysis

rustup component add rust-src

```

`rls-preview`, `rust-analysis` and `rust-src` are required for RLS support (including cross-referencing to the standard library, code completion and formatting).

# Cargo

Cargo is the go-to tool for managing Rust application and your own Rust developments (see [cargo](https://crates.io/) for detailed documentation). 

By default your Rust related tools will be stored in `~/.cargo`, this directory should be added to your `$PATH` environment. `cargo` and `rustup` works closely together, e.g., you may tell `cargo` to use a specific toolchain for the build. 

In order to get formatting to work you need to install `rustfmt-nightly`.

```

cargo install rustfmt-nightly

```

There is also another (old) crate named `rustfmt`, that can be compiled with the `stable` Rust compiler. The `rustfmt-nightly` is the *new* and improved formatter, that will eventually replace the old stable `rustfmt` (the generated binaries have the same name so do *not* install the stable version).

# Rust Crates

A crate is a unit of compilation, being either a library or an application. Crates are managed (compiled, installed, removed, updated, etc.) by the [cargo](https://crates.io/) tool. 

A *crate* is a unit of compilation, being either a *library* or an executable *application* (binary). Crates are managed (compiled, installed, removed, updated, etc.) by the [cargo](https://crates.io/) tool. 

`*.toml` files are used throughout Rust developments for giving configuration (meta) information (essentially replacing the need of Makefiles). The `Cargo.lock` file shows the cashed dependencies (you may delete the `Cargo.lock` file to force updating dependencies, `cargo clean` may not be enough).

Dependencies (may) include a minimal version, following the [semver](http://semver.org/) versioning standard.

# VSCODE support

## RLS 

[vscode](https://wiki.archlinux.org/index.php/Visual_Studio_Code) is the official integration test platform for the RLS development, and hence likely also to provide the best user experience. 

See [rls](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust) for installing the RLS extension.

You will need to pin the specific toolchain version used, by setting the `"rust-client.channel": "nightly-2018-01-10"` in your `vscode` *user* settings (this will be stored in a file `~/.config/Code/User/settings.json` and used for all your `vscode` projects. Settings may be set individually for each *workspace*, overriding the defaults. Regarding the  `"rust-client.channel"` setting, a *workspace* setting would force the specific version (overriding the default), and may not work when the code is distributed (as other developers may be on other toolchains).

For RLS to work, `vscode` need a path to the `rls-preview` library (using the environment variable `LD_LIBRARY_PATH` (Linux), `DYLD_LIBRARY_PATH` (OSX ?)). 

```

export LD_LIBRARY_PATH=$(rustc --print sysroot)/lib:$LD_LIBRARY_PATH

```

You may add this to your `~/.bash_profile`, and start vscode (`code` is the name of the executable) in a new terminal (to ensure that the `LD_LIBRARY_PATH` (Linux) `DYLD_LIBRARY_PATH` (OSX?) is correctly set). If `code` is run from your window manager (e.g., `plasma`), make sure that the environment is set correctly. 

Under the hood: `rustc --print sysroot` gives you the path to the root of the current toolchain. So its important that the toolchain is set correctly by `rustup` for this to work. 

`*.toml` files are used throughtout Rust developments for giving configuration (meta) information. The `Cargo.lock` file shows the cashed dependencies (you may delete the `Cargo.lock` file to force updating dependencies, `cargo clean may not be enough).

## GIT

You may choose to use the [gitlens](https://github.com/eamodio/vscode-gitlens) extension, to get integrated git support.

Dependencies (may) include a minimal version, eg `itm = "0.1.1"` indicates that at least version `0.1.1` in required (so `0.1.1`, `0.1.2`, `0.2.3` is Ok, while `0.1.0` will not suffice, and a version `1.0.0` would be considered a breaking change (major number changed) and not considered. Rust follows the [semver](http://semver.org/) versioning standard.

 No newline at end of file

## Native Debug

The [Native Debug](https://github.com/WebFreak001/code-debug) extension allows for debugging Rust application from within `vscode`. Native Debug supports both `lldb` (LLVM) and `gdb` (GNU)

debuggers. For embedded development, you will use the latter. See Embedded.md (TODO) for further details.

# Embedded Programming in Rust

# ARM Toolchain

Rust relying on LLVM is already a cross compiler, however currently linking to embedded targets are done using `binutils`. Under arch you can install the complete GNU toolchaion for ARM using the package `arm-none-eabi-gcc`, which also installs `arm-none-eabi-binutils`. (The package also installs `arm-none-eabi-gdb`, which you will use later for debugging.)

Rust relying on LLVM is already a cross-compiler, however currently linking to embedded targets are done using `binutils`. Under arch you can install the complete GNU toolchain for ARM using the package `arm-none-eabi-gcc`, which also installs `arm-none-eabi-binutils`. (The package also installs `arm-none-eabi-gdb`, which you will use later for debugging.)

# Openocd

In order to debug code on the ARM target you need to establish a connection, e.g., using [openocd](http://openocd.org/), available under arch as `openocd`. Later you will start `openocd` in the background using e.g.:

(Assuming that this is a `nucleo stm32f401re` target, programmed using the onboard `stlink-v2-1` interface.)

## port configuration

By default `openocd` listens at port `3333` for incoming gdb connections. If you want to program/dubug multiple targets using SWD (Serial Wire Debug) like offered by the `stlink` based interfaces you need one interface per target. In that case you may run several instances of `openocd` listening in on different ports. To that end the target configuration is defined in the `target/*.cfg`

By default `openocd` listens at port `3333` for incoming gdb connections. If you want to program/debug multiple targets using SWD (Serial Wire Debug) like offered by the `stlink` based interfaces you need one interface per target. In that case you may run several instances of `openocd` listening in on different ports. To that end the target configuration is defined in the `target/*.cfg`

```

```> cargo install xargo```

(Your top level module should give the crate-wide attribute `#![no_std]` in order to use `core` instead of `std` as the default library.)

(Your top-level module should give the crate-wide attribute `#![no_std]` in order to use `core` instead of `std` as the default library.)

# Using VS Code

## Rust support

 Install the `Rust(rls)` plugin (just search for `Rust` in the extensions, chose the plugin and install). Assuming you already have `rustup` and the Rust tools installed the required crates will be installed autematically. The RLS plugin is experimental but already quite useuful. If it fails installing you may check the [RLS git](https://github.com/rust-lang-nursery/rls), for further instructions (actually you can run the plugin from `java script` source.)

 Install the `Rust(rls)` plugin (just search for `Rust` in the extensions, chose the plugin and install). Assuming you already have `rustup` and the Rust tools installed the required crates will be installed automatically. The RLS plugin is experimental but already quite useful. If it fails to install you may check the [RLS git](https://github.com/rust-lang-nursery/rls), for further instructions (actually you can run the plugin from `javascript` source.)

## Debugging

    "request": "attach",

    "name": "Debug",

    "gdbpath": "/usr/bin/arm-none-eabi-gdb",

    "executable": "./target/thumbv7em-none-eabihf/debug/bluepill",

    "executable": "./target/thumbv7m-none-eabi/debug/bluepill",

    "target": ":3333",

    "remote": true,

    "autorun": [

        "set mem inaccessible-by-default off",

        "d breakpoints",

        "set remotetimeout 300",

        "load ./target/thumbv7em-none-eabihf/debug/bluepill",

        "load ./target/thumbv7m-none-eabi/debug/bluepill",

        "step",

        "monitor reset halt"

    ],

It launches `/usr/bin/arm-none-eabi-gdb` and attach the target on port `:3333`, the `:` indicates that the connection to be on the local host). It assumes `openocd` is running and has established a connection to the target.

Similarly a launch confirguration for release (optimised) builds:

Similarly a launch configuration for release (optimised) builds:

```javascript

{

    "type": "gdb",

    "request": "attach",

    "name": "Debug",

    "gdbpath": "/usr/bin/arm-none-eabi-gdb",

    "executable": "./target/thumbv7em-none-eabihf/release/bluepill",

    "executable": "./target/thumbv7m-none-eabi/release/bluepill",

    "target": ":3333",

    "remote": true,

    "autorun": [

        "set mem inaccessible-by-default off",

        "d breakpoints",

        "set remotetimeout 300",

        "load ./target/thumbv7em-none-eabihf/release/bluepill",

        "load ./target/thumbv7m-none-eabi/release/bluepill",

        "step",

        "monitor reset halt"

    ],

``` 

You may set specific settings in the `Cargo.toml` for each build type (`dev` for debug, `release` for release). Notice debugging of optimized code may be difficult as many symbols are *optimised out* and setting breakpoints may not give the desired results. To that end you may choose to use `asm::bkpt()` (defined in the [contex-m](https://github.com/japaric/cortex-m) crate) in the code instead of breakpoints in the debugger.  

## Compilation and Linking

The `xargo/cargo` build system will look into your `.cargo/config` for flags. The first example builds for the `m3` architecture while the second for the `m4` with *hard float* code. Notice, to use the *hard floats*, they need to be enabled in the ARM-core (not enabled at reset by default to save power...). You may have several configurations in the `.cargo/config`, and the `[build] = "..."` determinates the default configuration, it may be overridden e.g, by 

```

> xargo build ... --target thumbv7m-none-eabi

```

```

[target.thumbv7m-none-eabi]

runner = 'arm-none-eabi-gdb'

rustflags = [

  "-C", "link-arg=-Tlink.x",

  "-C", "linker=arm-none-eabi-ld",

  "-Z", "linker-flavor=ld",

]

[build]

target = "thumbv7m-none-eabi"

```

```

[target.thumbv7em-none-eabihf]

runner = 'arm-none-eabi-gdb'

rustflags = [

  "-C", "link-arg=-Tlink.x",

  "-C", "linker=arm-none-eabi-ld",

  "-Z", "linker-flavor=ld",

]

[build]

target = "thumbv7em-none-eabihf"

```

## A note on WFI

If your code hits a `WFI` (Wait For Interrupt), the MCU is put into a low power mode, and by default not accepting new debug request. Thus if trying to connect a new `gdb` session, it will fail (or even worse partially work, while not behaving correctly). To remedy this you may try:

* close `openocd` and restart it

* unplug the debugger (`stlink` probe), and re-plug it, you may need to hold the `reset` at startup to force the debugger and MCU into a correct state

If we want to overcome this problem altogether, there is a setting in the ARM-core debug unit that allows incoming connections on `WFI` (this feature is disabled by default to save power).

 No newline at end of file

# Rust Memory Model

The memory model is one unique feature that makes Rust stand out from other similar languages.

At heart, is uniqueness of references to mutable resources (memory locations). I.e., in *safe* Rust, one can either have a single mutable reference, or (one or) many immutable references to a resource, but never both (mutable and immutable references at the same time).

This property is enforced by the *borrow checker* in the `rustc` compiler, i.e., code which breaks these properties will be rejected with a compilation error.

There are several advantages with the Rust memory model. To name a few: 

* Foremost the Rust memory model is safe, i.e., for programs (written in *safe Rust*) that passes compilation the generated code will be free of unsafe memory accesses (and thus *memory safe*);

* The Rust memory model allows for "fearless programming", i.e., as a programmer you don't have to focus efforts on memory safety, the compiler will stop you if you do something potentially dangerous;

* Programming errors that indirectly lead to memory errors can be spoted at compile time. (E.g, attempting to change the lenght of an array `a` inside an iterator over `a` will be spotted by the compiler and yielt an error.);

* The Rust memory model allows for aggressive optimization, i.e., the compiler will host detailed information regarding the mutability of references and make *safe* assumpitions leading to efficient implementations.

## A bit of history

### Linear Types

Linear types has been studied in works of e.g., Wadler. Linear types and linearity can be used towards memory models.

In the Wadler type system, a linear value:

* is used exactly once;

* to which there exists exactly one pointer

This has gives the properties:

* no duplication: there exists at most one pointer to a linear value, so destructive update is safe;

* no discarding: every linear value has a use, which represents an explicit deallocation site, so garbage collection is not required;

* the real world (e.g., the state of the file system, or some I/O) can be modeled as a linear value.

In effect, linear values are *read/write*.

Wadler noted that the type system is

extremely restrictive. For instance, reading one element out of a linear array constitutes a use of the array, which forbids any further use of the array!

A workaround is to have the “get" operation return a (linear) pair of the value that was read and the (unchanged) array. This leads to a programming style where linear values are explicitly threaded. This style is heavy and over-sequentialised.

(Here, recall the *move* semantics of Rust, very similar.)

Moreover Wadler made a clear distinction between linear and non-linear types/values.

### Uniqueness types in Clean

Barendsen and Smetsers introduced type modes (*unique/non-unique*) in the `Clean` programming language, where  *unique* is similar to Wadlers *linear*.

Also here the real world is considered  *unique/linear*.

### C++ unique_ptr

More recently, C++ has adopted *unique pointers*, as a library extension.

However in comparison to the Rust memory model, analysis is out of reach to the compiler, and checked at run-time. Moreover, `move` is always expilict in C++. In effect what `move` does is to create a new pointer to the allocated resource and set the original pointer to `NULL`. If the user tries to access the old pointer, the run-time will abort withe a `NULL` deref error. (A poor-mans solution in comparison to Rust static checking).

## Rust Affine Type System

In comparison to a pure *linear* type system, Rust implements an *Affine*, where a resource *may* be used as most once (compared to the *must* be used exactly once.)

Rust also implemnets the concept of *shared* (borrowed immutable pointers). These are *non-Affine*, and we can have *0* or *N* pointer instance pointing to the same resource (these can be seen roughly as Wadlers *non-linear* types).

Furthemore Rust provides *mutable* pointers, with *Affine* behavior. However, ownership is borrowed (and implicitly returned on exit), in contrast to *move* semantics (under which a moved value is not returned implicitly). 

TODO: Some nice examples here....

## Limitations to Static (Compile Time) Analysis

The Rust compiler checks *safe* Rust code according to the safety invariants. However, it cannot deduce safety of all operations statically. In effect that would require full blown program analysis and proof over Rust programs. Instead the `rustc` compiler induces code for run-time verification to cases out of reach for the *borrow checker*.