README.md

# Firmware Development Guide

The goal of this document is to provide a set of best practices, design guidelines, and tooling
recommendations for developing firmware in Rust, particularly in `no_std` environments.

## Set `no_std` attribute

Rust's standard library relies on the presence of a rich OS. As a result, it isn’t available in
firmware environments. Firmware projects or crates should therefore be marked with `no_std` to
indicate that they do not use the std library.

Insert the following line at the top of `main.rs`/`lib.rs`.

```rust,ignore
#![no_std]
```

Tests might rely on the standard library since they are typically executed in a host environment.
Therefore, the `no_std` attribute should be conditionally applied when the build is not intended for
testing.

```rust,ignore
#![cfg_attr(not(test), no_std)]
```

## Avoid using `alloc`

Using a heap in firmware components can lead to non-deterministic behavior and potential
fragmentation issues. As a result, many firmware projects choose to avoid using a heap entirely.

Since a heap may not be available, relying on types from the alloc crate - such as `Vec` - can
restrict the crate's applicability. Instead, prefer using slices for function inputs and outputs
whenever possible. This approach allows the caller to manage memory allocation using the most
appropriate storage mechanism for their context.

```rust
fn numbers_with_alloc(n: usize) -> Vec<usize> {
    let mut result = Vec::new();
    for i in 0..n {
        result.push(i);
    }
    result
}

fn numbers_without_alloc(n: usize, result: &mut [usize]) {
    for i in 0..n {
        result[i] = i;
    }
}

let result: Vec<usize> = numbers_with_alloc(10);

let mut result: [usize; 10] = [0; 10];
numbers_without_alloc(10, &mut result);

// But now it still works with Vec too!
let mut result: Vec<usize> = vec![0; 10];
numbers_without_alloc(10, result.as_mut_slice());
```

## Derive or implement common traits for custom types

Rust provides a wide range of traits that allow custom types to integrate seamlessly with the
core and standard library. For instance, a slice can be sorted if its element type implements the
`Ord` trait, and if the element type implements `PartialEq`, it’s possible to check whether a slice
contains a specific item. Implementing these traits for your custom types greatly increases their
usability. Avoid creating ad-hoc methods for common operations, prefer standard traits like `From`
or `TryFrom` for type conversions.

There are two main ways to implement a trait: by deriving it or by writing an explicit
implementation. When a type's fields already implement a trait, using `#[derive]` is often enough
to generate the trait implementation automatically. However, if the default behavior isn’t
suitable, you can manually implement the trait to customize its logic.

### Common traits

* `Debug` - Enables printing the value using the `"{:?}"` formatter.
* `Display` - Enables printing the value using the `"{}"` formatter. `Display` is similar to
  `Debug`, but `Display` is for user-facing output, and so cannot be derived.
* `Default` - Provides a `default()` function for creating default instance.
* `Clone` - Enables explicit `clone()`-ing of the type.
* `Copy` - Enable implicit copying of the type. Do not use it for large types to avoid unnecessary
  copying.
* `PartialEq` - Provides `==` and `!=` operators.
* `Eq` - The implementor promises that `a == a`, i.e. the type is reflexive. This is not true for
   floating point numbers where `NaN != Nan`.
* `PartialOrd` - Provides `<`, `<=`, `>`, and `>=` operators.
* `Ord` - Trait for types that form a total order.
* `From<T>` -  Used to do value-to-value conversions while consuming the input value. It is the
  reciprocal of `Into`. Implementing `From` over `Into` is preferred, because `From` automatically
  provides an `Into` implementation as well.
* `TryFrom<T>`- Simple and safe type conversions that may fail in a controlled way under some
  circumstances. It is the reciprocal of `TryInto`.

### Example

```rust
#[derive(Debug, Default, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct Address {
    city: String,
    street: String,
    house_number: u32
}

fn get_addresses() -> Vec<Address> {
    vec![Address {
        city: "Cambridge".to_string(),
        street: "Fulbourn Rd".to_string(),
        house_number: 110,
    }]
}

let mut addresses: Vec<Address> = get_addresses();

// Debug trait
println!("{:?}", addresses[0]);

// Default trait
let empty_address = Address::default();

// Clone trait
let empty_clone = empty_address.clone();

// PartialEq trait
let has_arm_address = addresses.contains(&Address {
    city: "Cambridge".to_string(),
    street: "Fulbourn Rd".to_string(),
    house_number: 110,
});

// Ord trait
addresses.sort();
```

## Minimize and document unsafe code

Maintaining and reviewing unsafe code demands additional effort, so it's best to keep its usage to
a minimum. In most cases unsafe code can be avoided by using an existing crate that provides a safe
wrapper around the unsafe logic. For example, `zerocopy` enables the developer to convert between
types, along all the necessary size and alignment checks.

During firmware development, writing some unsafe code is often unavoidable. Whenever you use unsafe
features, clearly document how the necessary conditions for safety are satisfied to justify the use
of unsafe blocks.

When defining an unsafe function, always specify the safety requirements that callers must uphold to
use the function correctly.

```rust
# struct BootInfo(u32);

// SAFETY: The address is mapped statically and nothing else references it.
let boot_info = unsafe {  &*(0x8000_0000 as *const BootInfo) };

/// # Safety
///
/// Before calling this function, ensure that all pending writes have been
/// flushed and there are no references to the address.
unsafe fn unmap_memory(address: u64) {
    // [...]
}
```

Add the following lines to `Cargo.toml` in order to enforce these rules by Clippy.

```toml
[lints.clippy]
missing_safety_doc = "deny"
undocumented_unsafe_blocks = "deny"
```

## Do not reinvent the ~~wheel~~ crate

Use popular crates instead of reimplementing a functionality. `cargo` provides great ways of reusing
code and `crates.io` provides high quality crates. On the other hand, try to minimize the number of
dependencies for supply chain, code size and build time reasons.

[npm left-pad incident](https://en.wikipedia.org/wiki/Npm_left-pad_incident)

Recommended crates to use in firmware project:

### bitflags

&#128279; [bitflags](https://crates.io/crates/bitflags)

Provides a macro to define typesafe bitflags for managing sets of binary flags (single-bit). Not
suitable for multi-bit fields.

```rust
bitflags::bitflags! {
    struct Permissions: u32 {
        const READ    = 0b001;
        const WRITE   = 0b010;
        const EXECUTE = 0b100;
    }
}

let perms = Permissions::READ | Permissions::WRITE;
let is_executable = perms.contains(Permissions::EXECUTE);
```

### embedded-hal

&#128279; [embedded-hal](https://crates.io/crates/embedded-hal)

Provides hardware abstraction layers for embedded system as a family of crates
(`embedded-hal`, `embedded-hal-async`, `embedded-hal-nb`, `embedded-io`, etc.). Peripheral drivers
should implement the suitable traits of these crates in order to increase interoperability.

### num_enum

&#128279; [num_enum](https://crates.io/crates/num_enum)

Rust does not have a built-in way of converting from integers to enums. The `num_enum` crate
provides utilities for defining enums with explicit integer representations and conversions between
them safely.

```rust
use num_enum::{TryFromPrimitive, TryFromPrimitiveError};
use core::convert::TryFrom;

#[derive(Debug, TryFromPrimitive, PartialEq, Eq)]
#[repr(u8)]
enum Command {
    Start = 1,
    Stop = 2,
}

assert_eq!(Ok(Command::Start), Command::try_from(1u8));
assert_eq!(Ok(Command::Stop), Command::try_from(2u8));
assert!(Command::try_from(3u8).is_err());
```

### safe-mmio

&#128279; [safe-mmio](https://crates.io/crates/safe-mmio)

For MMIO peripheral access use the `safe-mmio` crate. This crates provides primitives for tracking
the lifetime and ownership of an MMIO peripheral and for defining different types of peripherals
registers.

```rust,no_run
use core::ptr::NonNull;
use safe_mmio::{
    field,
    fields::{ReadOnly, ReadPure, ReadWrite, WriteOnly},
    UniqueMmioPointer,
};

#[repr(C)]
struct UartRegisters {
    data: ReadWrite<u8>,
    status: ReadPure<u8>,
    pending_interrupt: ReadOnly<u8>,
}

// SAFETY:
// The UART peripherals at 0x900_0000 is statically mapped for the lifetime of
// the application and nothing else references it.
let mut uart_registers: UniqueMmioPointer<UartRegisters> =
    unsafe { UniqueMmioPointer::new(NonNull::new(0x900_0000 as _).unwrap()) };

field!(uart_registers, data).write(b'x');
```

### spin

&#128279; [spin](https://crates.io/crates/spin)

Implements simple spinlocks for `no_std` environments without relying on OS primitives. Use
`spin::Once` for global/static variable lazy initialization.

```rust
use spin::Mutex;

static DATA: Mutex<u32> = Mutex::new(0);

fn increment() {
    let mut data = DATA.lock();
    *data += 1;
}
```

### thiserror

&#128279; [thiserror](https://crates.io/crates/thiserror)

This library provides a convenient derive macro for the standard library’s `core::error::Error`
trait. It makes creating custom error types easier by

```rust
use thiserror::Error;

#[derive(Debug, Error)]
enum CustomError {
    #[error("generic error")]
    GenericError,
    #[error("invalid capacity: {0}")]
    InvalidCapacity(usize),
    #[error("unknown command index: {0}")]
    UnknownCommandIndex(u32),
}
```

### uuid

&#128279; [uuid](https://crates.io/crates/uuid)

Use the `uuid` crate for parsing/handling UUID/GUID values. It provides functions for converting
between the `Uuid` type and strings, bytes and other representations.

```rust
use uuid::{uuid, Uuid};

const ID: Uuid = uuid!("67e55044-10b1-426f-9247-bb680e5fe0c8");
let my_uuid =
    Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").expect("Failed to parse UUID");

let bytes: &[u8; 16] = my_uuid.as_bytes();
```

### zerocopy

&#128279; [zerocopy](https://crates.io/crates/zerocopy)

Enables zero-copy parsing and serialization of fixed-layout types using safe abstractions. Zerocopy
ensures that the source and destination types are suitable for conversion and they have a matching
size and alignment.

```rust
use zerocopy::{FromBytes, IntoBytes, KnownLayout, Immutable, transmute};

#[derive(FromBytes, IntoBytes, KnownLayout, Immutable)]
#[repr(C, packed)]
struct Packet {
    header: u16,
    payload: u32,
}

let raw: [u8; 6] = [0x01, 0x02, 0x03, 0x04, 0x05, 0x06];
let packet = Packet::read_from(&raw[..]).unwrap();
let raw_serialized = packet.as_bytes();
assert_eq!(raw_serialized, [0x01, 0x02, 0x03, 0x04, 0x05, 0x06]);

let one_dimensional: [u8; 8] = [0, 1, 2, 3, 4, 5, 6, 7];
let two_dimensional: [[u8; 4]; 2] = transmute!(one_dimensional);
assert_eq!(two_dimensional, [[0, 1, 2, 3], [4, 5, 6, 7]]);
```

## Recommended tools

### rustfmt

&#128279; [rustfmt](https://github.com/rust-lang/rustfmt)

Rust has an official style guide that ensures consistent formatting across the Rust ecosystem.
`cargo fmt` automatically formats the code according to the official style guide. Most editors can
integrate rustfmt to format on save.

### Clippy

&#128279; [Clippy](https://github.com/rust-lang/rust-clippy)

Clippy is the official Rust linter tool. It can emit various style, performance, etc. issues.
Always address the issues pointed out by Clippy to improve code quality.

### Cargo Vet

&#128279; [Cargo Vet](https://github.com/mozilla/cargo-vet)

Cargo provides an easy way for using third party crates, however this introduces the possibility of
supply chain attacks. An attacker can take over a dependency or push a malicious change into it.
Cargo Vet is a tool for supply chain auditing and it only allows the use of audited crate versions.

## Pre-release checklist

Before releasing the crate/project go thought the following action items.

* Update version number in `Cargo.toml`
* Update readme/changelog
* Run the following commands

```sh
cargo update # Update dependencies
cargo vet    # Run audit check
cargo build  # Build project
cargo test   # Build and run tests
cargo clippy # Run linter
```

## General advice

* `use` only what's needed.
* Create `const` variables for magic numbers.
* Try to limit the visibility of types and functions using `pub`, `pub(crate)`, etc. modifiers.
* The fields of enum variants inherit the visibility of the type, however this is not true for
  struct field. Make sure that struct fields have the correct visibility if they are intended to be
  accessed outside of the defining module.

--------------

*Copyright 2025 Arm Limited and/or its affiliates <open-source-office@arm.com>*

*Arm is a registered trademark of Arm Limited (or its subsidiaries or affiliates).*