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/esp_spi"
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 |
esp_spi.dodo |
BUFFER_SIZE
Constant · Source
Bytes in the data buffer, the most one run moves without DMA.
pub const BUFFER_SIZE: usize = 64
MAX_DMA_BYTES
Constant · Source
The most bytes one DMA run moves: MS_DLEN counts 2^18 bits.
pub const MAX_DMA_BYTES: usize = 32_768
Divider
Struct · Source
The clock divider for one SCK frequency, from
divider.
pub struct Divider {
// The function clock it divides.
pub clock_hz: u32
// The CLOCK register's value.
pub value: u32
// The resulting SCK frequency.
pub frequency_hz: u32
}
divider
Function · Source
The fastest SCK at most
frequency_hzfrom a function clock ofclock_hz: the function clock itself, or divided by 2 to 1024. InvalidInput below clock_hz / 1024.
pub fn divider(clock_hz: u32, frequency_hz: u32) -> Divider!hal.Error
Controller
Struct · Source
An SPI bus master on one controller with registers R. Implements the std/embedded/hal SPI bus protocol and its polling form.
pub struct Controller<R: hal.Registers>: hal.Spi + hal.SpiPoll {
// Private implementation fields omitted.
}
Controller.new
Function · Source
Configure a controller fresh out of reset as a master in
modeat the SCK frequency ofdivider.
pub fn new(registers: R, divider: Divider, mode: hal.SpiMode) -> Controller<R>
Controller.frequency_hz
Function · Source
The SCK frequency, the fastest the controller makes up to the request.
pub fn frequency_hz(&self) -> u32
Controller.set_frequency
Function · Source
Change the SCK frequency; 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 for the next transfer.
pub fn set_mode(&mut self, mode: hal.SpiMode)
Controller.set_hardware_select
Function · Source
Drive the controller’s chip select output CS0 around each transfer, or leave it off (high). The chip package routes it to a pin.
pub fn set_hardware_select(&mut self, on: bool)
Controller.transfer
Function · Source
Full-duplex exchange in place: each byte sent is replaced by the byte read. Busy while a polled transfer runs.
pub fn transfer(&mut self, bytes: &mut[u8]) -> void!hal.Error
Controller.write
Function · Source
Send
bytes, ignoring what comes back.
pub fn write(&mut self, bytes: &[u8]) -> void!hal.Error
Controller.poll_transfer
Function · Source
Advance a full-duplex exchange of
bytesin place without waiting: the first call starts a run of up to 64 bytes, and each later call that finds the run over stores what it read and starts the next; true once every byte has been exchanged. See hal.SpiPoll. InvalidInput for a slice of another length, or a write, while a polled transfer runs. An empty slice is done at once.
pub fn poll_transfer(&mut self, bytes: &mut[u8]) -> bool!hal.Error
Controller.poll_write
Function · Source
Advance a write of
bytes, discarding what arrives, as forpoll_transfer.
pub fn poll_write(&mut self, bytes: &[u8]) -> bool!hal.Error
Controller.cancel
Function · Source
Abandon the running polled transfer, if any, once the run on the wire is complete (at most 64 bytes’ time), and raise a hardware chip select.
pub fn cancel(&mut self)
Controller.is_busy
Function · Source
True while a polled transfer runs.
pub fn is_busy(&self) -> bool
Controller.prepare_dma
Function · Source
Set up a DMA run of
countbytes, sending and, withreceive, receiving at the same time, and switch the data phases to DMA. The chip package then starts its DMA channel’s links to this controller and callsstart_dma. Busy while a polled transfer or a DMA run runs; InvalidInput for 0 or more than MAX_DMA_BYTES.
pub fn prepare_dma(&mut self, count: usize, receive: bool) -> void!hal.Error
Controller.start_dma
Function · Source
Start the DMA run that
prepare_dmaset up, once the chip package has started its DMA channel: the FIFOs between the controller and memory start empty.
pub fn start_dma(&mut self)
Controller.dma_done
Function · Source
True once the DMA run has shifted its last bit. The data received may still be on its way to memory; the DMA channel says when it is there.
pub fn dma_done(&mut self) -> bool
Controller.end_dma
Function · Source
End a DMA run that is done, or abandon one, and switch the data phases back to the data buffer. An abandoned run stops after its current bit, waiting at most a byte’s time. Overrun if the DMA channel took received data too slowly for the clock, so bytes were lost; data to send that comes late only pauses the clock.
pub fn end_dma(&mut self) -> void!hal.Error
Controller.release
Function · Source
Give back the registers, with the controller’s clocks off.
pub fn release(self) -> R
Target
Struct · Source
An SPI target (slave) on one controller with registers R: a master drives the clock and the chip select, and the target shifts out what it queued while it shifts in what the master sends, most significant bit first, in the SpiMode given. It implements hal.SpiTarget.
The controller exchanges whole transactions, from the chip select going low to its rising again, through its 64-byte data buffer: the bytes queued before a transaction starts go out in it, the rest of what the master clocks reads 0xFF, and the bytes the master sends arrive once the chip select rises. A transaction beyond 64 bytes loses the excess, which the next read reports as Overrun. After each transaction the controller waits to be armed again, which
queueandreaddo, so the master must leave the program time to poll between transactions: a transaction clocked meanwhile is not received, and the target cannot tell. Up to 128 received bytes wait forread; while they would not fit, the target is not armed again.
pub struct Target<R: hal.Registers>: hal.SpiTarget {
// Private implementation fields omitted.
}
Target.new
Function · Source
Configure a controller fresh out of reset as a target in
mode, and arm it, with nothing queued.
pub fn new(registers: R, mode: hal.SpiMode) -> Target<R>
Target.queue
Function · Source
Queue
bytesto send in the master’s next transactions, as many as there is room for (64 bytes at most wait), without waiting; returns how many. Bytes queued while the target waits for a transaction go out in it if the master has not begun clocking it yet, else in the one after. Never fails: the error is there for hal.SpiTarget.
pub fn queue(&mut self, bytes: &[u8]) -> usize!hal.Error
Target.read
Function · Source
The bytes the master sent in finished transactions since the last call, up to
buffer.len, without waiting; returns how many. Overrun if a transaction ran beyond the 64-byte buffer and lost bytes; the bytes received stay for the next read.
pub fn read(&mut self, buffer: &mut[u8]) -> usize!hal.Error
Target.unsent
Function · Source
The bytes queued and not yet sent.
pub fn unsent(&self) -> usize
Target.release
Function · Source
Stop, and give back the registers with the controller’s clocks off.
pub fn release(self) -> R