std/embedded/hal

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/hal"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias	Package	Source file
`cpu`	`core/cpu`	hal.dodo
`ptr`	`core/ptr`	hal.dodo

`Error`

Enum · Source

Bus and device failures shared by every driver and chip implementation. A single payload-free enum keeps drivers composable and comparable with ==.

pub enum Error {
    // The device did not respond or a flag did not change in time.
    Timeout,
    // No device acknowledged its address or a data byte.
    NoAcknowledge,
    // Electrical or protocol fault, including lost bus arbitration.
    Bus,
    // Data arrived faster than it was consumed.
    Overrun,
    // The peripheral is in use or not ready for this request.
    Busy,
    // An argument is outside what the device or bus accepts.
    InvalidInput,
    // The implementation does not support this operation.
    Unsupported
}

`error_name`

Function · Source

pub fn error_name(error: Error) -> &str from(static)

`I2C_STANDARD_HZ`

Constant · Source

Common I2C bus frequencies: standard mode, fast mode, and fast mode plus. Every device supports standard mode; most sensors also fast mode.

pub const I2C_STANDARD_HZ: u32 = 100_000

`I2C_FAST_HZ`

Constant · Source

pub const I2C_FAST_HZ: u32 = 400_000

`I2C_FAST_PLUS_HZ`

Constant · Source

pub const I2C_FAST_PLUS_HZ: u32 = 1_000_000

`SpiMode`

Enum · Source

SPI clock polarity and phase, as numbered in device datasheets. Mode 0, clock idle low and data sampled on the rising edge, is the most common.

pub enum SpiMode {
    // Clock idles low; data is sampled on the rising (first) edge.
    Mode0,
    // Clock idles low; data is sampled on the falling (second) edge.
    Mode1,
    // Clock idles high; data is sampled on the falling (first) edge.
    Mode2,
    // Clock idles high; data is sampled on the rising (second) edge.
    Mode3
}

`encode`

Function · Source

value moved into the position of mask. Traps if it does not fit, so a wrong value never silently changes a neighbouring field.

pub fn encode<T>(mask: T, value: T) -> T

`decode`

Function · Source

The field mask extracted from a whole register value.

pub fn decode<T>(mask: T, register: T) -> T

`Reg`

Struct · Source

One memory-mapped register holding T (u8, u16, u32, or u64 up to the target pointer width). Every access is a single volatile load or store of T; the compiler never merges, removes, or splits it.

A Reg is move-only. Owning it is the permission to touch that register, so build peripheral structs from Reg fields and hand them out once.

pub struct Reg<T> {
    // Private implementation fields omitted.
}

`Reg.at`

Function · Source

SAFETY: address must be a valid, T-aligned device register for this target, accessible with T-sized loads and stores, and no other handle or code may access it in a conflicting way while this handle exists.

pub unsafe fn at(address: usize) -> Reg<T>

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

`Reg.address`

Function · Source

pub fn address(&self) -> usize

`Reg.read`

Function · Source

pub fn read(&self) -> T

`Reg.write`

Function · Source

pub fn write(&mut self, value: T)

`Reg.modify`

Function · Source

Read-modify-write: clear the clear bits, then set the set bits. Not atomic with respect to interrupts; wrap shared registers in a Critical section or use the chip’s set/clear aliases instead.

pub fn modify(&mut self, clear: T, set: T)

`Reg.set_bits`

Function · Source

pub fn set_bits(&mut self, mask: T)

`Reg.clear_bits`

Function · Source

pub fn clear_bits(&mut self, mask: T)

`Reg.any`

Function · Source

True when any bit in mask reads as one.

pub fn any(&self, mask: T) -> bool

`Reg.get`

Function · Source

The value of the field mask.

pub fn get(&self, mask: T) -> T

`Reg.set`

Function · Source

Read-modify-write of the field mask. Traps if value does not fit.

pub fn set(&mut self, mask: T, value: T)

`Reg.wait_set`

Function · Source

Poll until every bit in mask reads one, at most attempts reads. Use it for ready flags; a stuck device then yields Error.Timeout instead of hanging forever.

pub fn wait_set(&self, mask: T, attempts: u32) -> void!Error

`Reg.wait_clear`

Function · Source

Poll until every bit in mask reads zero, at most attempts reads.

pub fn wait_clear(&self, mask: T, attempts: u32) -> void!Error

`RegisterBlock`

Struct · Source

A peripheral’s 32-bit registers at byte offsets from one base address. Implements the register block protocol, so drivers in std/embedded/peripheral reach the hardware through it. Every access is one volatile 32-bit load or store, like Reg<u32>. Move-only: owning it is the permission to use the whole block.

pub struct RegisterBlock {
    // Private implementation fields omitted.
}

`RegisterBlock.at`

Function · Source

SAFETY: base must be the 4-aligned base address of one peripheral on this target, every offset its driver uses must be a valid 32-bit register of it, and no other handle or code may access those registers in a conflicting way while this handle exists.

pub unsafe fn at(base: usize) -> RegisterBlock

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

`RegisterBlock.base`

Function · Source

pub fn base(&self) -> usize

`RegisterBlock.read`

Function · Source

pub fn read(&mut self, offset: usize) -> u32

`RegisterBlock.write`

Function · Source

pub fn write(&mut self, offset: usize, value: u32)

`Critical`

Struct · Source

Masks interrupts on the current core while it is alive and restores the previous state when dropped, so sections nest correctly:

section := hal.Critical.enter() unsafe { TICKS += 1 } core.drop(section)

Bare-metal Cortex-M and RISC-V mask interrupts; hosted OS targets have no interrupts visible to programs and make this a no-op. It never excludes other threads or cores; use std/sync for those.

pub struct Critical {
    // Private implementation fields omitted.
}

`Critical.enter`

Function · Source

pub fn enter() -> Critical

`write_pin`

Function · Source

Drive an output pin to high.

pub fn write_pin<P>(pin: &mut P, high: bool)

`delay_ms`

Function · Source

pub fn delay_ms<D>(delay: &mut D, milliseconds: u32)

`read_register`

Function · Source

pub fn read_register<B>(bus: &mut B, address: u8, register: u8) -> u8!Error

`read_registers`

Function · Source

pub fn read_registers<B>(bus: &mut B, address: u8, first: u8, buffer: &mut[u8]) -> void!Error

`write_register`

Function · Source

pub fn write_register<B>(bus: &mut B, address: u8, register: u8, value: u8) -> void!Error

`SpiDevice`

Struct · Source

One device on a shared SPI bus, selected by an active-low chip-select pin. The device owns its pin; the bus is passed to each transaction, so several devices share one bus and the borrow checker keeps transactions apart.

pub struct SpiDevice<P> {
    // Private implementation fields omitted.
}

`SpiDevice.new`

Function · Source

Takes the chip-select pin and deselects the device.

pub fn new(select: P) -> SpiDevice<P>

`SpiDevice.transfer`

Function · Source

Full-duplex exchange in place with the device selected.

pub fn transfer<B>(&mut self, bus: &mut B, bytes: &mut[u8]) -> void!Error

`SpiDevice.write`

Function · Source

pub fn write<B>(&mut self, bus: &mut B, bytes: &[u8]) -> void!Error

`SpiDevice.write_read`

Function · Source

Write command, then read buffer.len bytes in the same selection.

pub fn write_read<B>(&mut self, bus: &mut B, command: &[u8], buffer: &mut[u8]) -> void!Error

`SpiDevice.release`

Function · Source

Give back the chip-select pin.

pub fn release(self) -> P