Ferrous Systems Rust Training

The Rust standard library (libstd) provides essential primitives for high-productivity development:

• Filesystem & I/O: Path handling, filesystem access, and I/O traits for files, strings, and sockets.
• Concurrency: Threads, Mutexes, Condition Variables, and Channels.
• Data Structures: Growable arrays (Vec), hash-tables, B-Trees, and Strings.
• Text: First-class Unicode support.
• Networking: IPv4/IPv6, TCP, and UDP support.
• System: Heap allocation, environment variables, CLI arguments, and time handling (Duration, Instant).

The demo contains five specific binaries located in ./src/bin designed to run in a QEMU-emulated AArch64 Arm Cortex-A system. All binaries utilize defmt for logging.

• defmt: Prints defmt logs at various levels.
• global_uart: Sets up a UART as a global variable and prints to it.
• panic: Demonstrates panic handling behavior.
• uart: Prints to the first available UART.
• with_heap: Demonstrates heap allocation by setting up a heap allocator and using the format! macro to generate and print heap-allocated strings.

Rust is a free and open-source systems programming language designed to empower developers to build reliable and efficient software. It focuses on three core pillars:

1. Safety: Preventing common programming errors.
2. Performance: Providing high-speed execution comparable to C/C++.
3. Productivity: Offering modern tooling and developer ergonomics.

Rust is highly portable and cross-platform, supporting Windows, macOS, Linux, iOS, Android, WebAssembly, and bare-metal embedded systems. It can also import and export C-compatible libraries, making it suitable for integrating into existing C/C++ codebases or creating extensions for languages like Python.

fn main() {
    println!("Hello, world!");
}

Ferrocene is a qualified version of the Rust toolchain designed for safety-critical applications. Unlike a subset of Rust, it is a downstream of The Rust Project that uses the actual Rust language.

Key characteristics include:

• Qualified: Certified per ISO 26262 (ASIL D) and IEC 61508 (SIL 4).
• Open Source: Licensed under MIT or Apache-2.0.
• Long-term Stable: Provides stable releases with support and tracking of known problems.
• Warranty & Support: Includes a warranty for compiler bugs and access to support/binary downloads via subscription.
• Independent Testing: Uses a separate, parallel CI pipeline to the Rust Project to produce artifacts required for qualification.

The mdbook-stripelineno pre-processor is used to convert code block syntax from a format compatible with reveal.js (which includes line ranges like [1|2-3|4]) into a format compatible with mdbook.

Specifically, it converts syntax like:

...

into the standard mdbook format:

...

This ensures that line-numbering metadata intended for slides does not break the rendering of code blocks in mdbook.

// Input format (reveal.js style)
```rust no_run [1|2-3|4]
fn example() {}
```

// Output format (mdbook compatible)
```rust,no_run
fn example() {}
```

defmt (Deferred Formatter) is a logging framework designed for microcontrollers. Unlike classical logging which stores format strings in Flash and transmits them over UART, defmt interns strings into a .defmt section within the ELF file.

Key mechanics:

• Strings: Stored in the ELF file on your host machine, not in the microcontroller's Flash.
• Data: Arguments are packed in a compact binary format and transmitted over the wire.
• Reconstruction: A host-side tool uses the exact ELF file used during compilation to reconstruct the log messages.

Benefits:

• Significantly less Flash usage.
• Reduced data transfer requirements.

Requirements:

• You must use a compatible host-side viewer tool.
• You must provide the exact ELF file that was used to build the binary running on the chip.

Unsafe Rust allows you to perform operations that the standard Rust type system cannot guarantee are safe. This is necessary for low-level memory manipulation or interfacing with external code.

Unsafe code is permitted to:

• Freely access memory.
• Dereference raw pointers.
• Call external functions (FFI).
• Declare values as Send and Sync.
• Write to unsynced global variables.

The following are NOT considered unsafe:

• Conversion to raw pointers.
• Memory leaks.

An Iterator is an object that produces a sequence of items one at a time by implementing a .next() method. This method returns Some(data) for each item and None once the sequence is exhausted.

Key characteristics:

• Stateful: The iterator object holds the current state of the iteration.
• Lazy: Iterators do not perform work until they are actually polled (e.g., in a loop or by a consumer method).
• On-the-fly calculation: Iterators can derive values from a collection, calculate items on-the-fly, or wrap and transform other iterators.

A Peripheral Access Crate (PAC) sits at the bottom of the hardware abstraction stack. It provides low-level access to the memory-mapped peripherals of a Microcontroller Unit (MCU).

Key concepts:

• Memory Mapped Peripherals: Hardware blocks (like a UART/serial port) that are accessed via specific memory addresses.
• Registers: The interface to peripherals, comprised of one or more bitfields. The specific layout and bitfield values are defined in the MCU's datasheet.
• Instances: Multiple peripherals may share the same register layout but exist at different base addresses (e.g., UART0, UART1).