std/embedded/peripheral/pl022

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/peripheral/pl022"

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
`hal`	`std/embedded/hal`	pl022.dodo

`Divisors`

Struct · Source

The clock dividers for one SPI clock frequency, from divisors.

pub struct Divisors {
    // The controller's input clock, in hertz.
    pub clock_hz: u32
    // The prescaler, an even number from 2 to 254.
    pub prescale: u32
    // The second divider, 1 to 256.
    pub rate: u32
    // The resulting SPI clock, clock_hz / (prescale * rate), in hertz.
    pub frequency_hz: u32
}

`divisors`

Function · Source

The fastest SPI clock from an input clock of clock_hz that does not exceed frequency_hz. The fastest possible is clock_hz / 2; a request above it gets that. InvalidInput below clock_hz / 65024, about 1.9 kHz at 125 MHz, the slowest possible.

pub fn divisors(clock_hz: u32, frequency_hz: u32) -> Divisors!hal.Error

`Controller`

Struct · Source

An SPI bus master on one PL022 with registers R, a value with the register block protocol of std/embedded/hal. Implements the std/embedded/hal SPI bus protocol.

pub struct Controller<R> {
    // Private implementation fields omitted.
}

`Controller.new`

Function · Source

Configure a controller fresh out of reset as a master with divisors, computed from the clock that feeds it, and mode, and enable it.

pub fn new(registers: R, divisors: Divisors, mode: hal.SpiMode) -> Controller<R>

`Controller.frequency_hz`

Function · Source

The SPI clock frequency, in hertz.

pub fn frequency_hz(&self) -> u32

`Controller.set_frequency`

Function · Source

Change the clock between transfers, for example to talk to devices with different limits on a shared bus. InvalidInput leaves it unchanged.

pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error

`Controller.set_mode`

Function · Source

Change the clock polarity and phase between transfers.

pub fn set_mode(&mut self, mode: hal.SpiMode)

`Controller.set_loopback`

Function · Source

Connect the transmitter to the receiver inside the controller, so every transfer reads back what it sent and the pins stay idle. Meant for self-tests.

pub fn set_loopback(&mut self, on: bool)

`Controller.transfer`

Function · Source

Send bytes and replace each with the byte received at the same time. Overrun if received bytes were lost to a full receive FIFO, which the driver’s pacing prevents unless something else used the controller.

pub fn transfer(&mut self, bytes: &mut[u8]) -> void!hal.Error

`Controller.write`

Function · Source

Send bytes and discard what arrives. Returns once the last bit has left, so a chip select can be raised right after.

pub fn write(&mut self, bytes: &[u8]) -> void!hal.Error

`Controller.release`

Function · Source

Disable the controller and give back its registers.

pub fn release(self) -> R

`Bus`

Struct · Source

A PL022 on the chip, as chip packages hand it to applications. It implements the std/embedded/hal SPI bus protocol like Controller but keeps the register block: RegisterBlock trusts its owner with every offset, which only the driver may be.

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

`Bus.at`

Function · Source

SAFETY: as for hal.RegisterBlock.at, with base a PL022 whose reset and pins the caller has set up and that only this bus uses.

pub unsafe fn at(base: usize, divisors: Divisors, mode: hal.SpiMode) -> Bus

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

`Bus.transfer`

Function · Source

pub fn transfer(&mut self, bytes: &mut[u8]) -> void!hal.Error

`Bus.write`

Function · Source

pub fn write(&mut self, bytes: &[u8]) -> void!hal.Error

`Bus.frequency_hz`

Function · Source

The clock frequency, in hertz: the fastest the controller can make that does not exceed the requested one.

pub fn frequency_hz(&self) -> u32

`Bus.set_frequency`

Function · Source

Change the clock between transfers, for devices with different limits on one bus.

pub fn set_frequency(&mut self, frequency_hz: u32) -> void!hal.Error

`Bus.set_mode`

Function · Source

Change the clock polarity and phase between transfers.

pub fn set_mode(&mut self, mode: hal.SpiMode)

`Bus.set_loopback`

Function · Source

Loop the transmitter back to the receiver inside the chip, for self-tests: transfers read back what they send.

pub fn set_loopback(&mut self, on: bool)

`Bus.release`

Function · Source

Disable the controller and return its base address, for the chip package to take the bus back.

pub fn release(self) -> usize