API referencestd/embedded

std/embedded/peripheral/pl011

Public declarations, types, methods, and source contracts for std/embedded/peripheral/pl011.

On this page

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/pl011"

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 pl011.dodo
hal std/embedded/hal pl011.dodo
io std/io pl011.dodo
serial std/embedded/hal/serial pl011.dodo

RX_INTERRUPT

Constant · Source

Interrupt sources, as bits of listen, ignore, pending_interrupts, and clear_interrupts. The controller raises its one interrupt line while any listened-to source is pending; the chip package names the line, such as UART0_IRQ, for an @interrupt handler.

RX_INTERRUPT: the receive FIFO holds 24 bytes or more (3/4 full). RX_TIMEOUT_INTERRUPT: received bytes have waited for 32 bit times with no more arriving, so a handler also hears about a short message. Both stay pending until reads drain the FIFO below their condition.

pub const RX_INTERRUPT: u32 = 1 << 4

TX_INTERRUPT

Constant · Source

The transmit FIFO has drained to 16 bytes or fewer: room to write more. Pending until writes fill it again or clear_interrupts.

pub const TX_INTERRUPT: u32 = 1 << 5

RX_TIMEOUT_INTERRUPT

Constant · Source

pub const RX_TIMEOUT_INTERRUPT: u32 = 1 << 6

ERROR_INTERRUPTS

Constant · Source

A received frame had a framing or parity error, was a break, or found the receive FIFO full. Pending until clear_interrupts.

pub const ERROR_INTERRUPTS: u32 = 0xF << 7

DEFAULT_POLL_LIMIT

Constant · Source

Status polls without progress before a wait for output gives up.

pub const DEFAULT_POLL_LIMIT: u32 = 10_000_000

NO_POLL_LIMIT

Constant · Source

A poll limit of zero waits as long as it takes.

pub const NO_POLL_LIMIT: u32 = 0

FRAMING_ERROR

Constant · Source

Receive errors: a failed read’s io.Error has kind Other and these bits in its code. A byte with a framing or parity error, or a break, is dropped: the line is noisy, the two ends disagree on the baud rate or format, or the other end holds the line low. An overrun means bytes were lost because the receive FIFO was full: the bytes read are good, but bytes are missing among them.

pub const FRAMING_ERROR: i32 = 1

PARITY_ERROR

Constant · Source

pub const PARITY_ERROR: i32 = 2

BREAK

Constant · Source

pub const BREAK: i32 = 4

OVERRUN

Constant · Source

pub const OVERRUN: i32 = 8

Divisors

Struct · Source

The baud rate divisor for one baud rate, from divisors.

pub struct Divisors {
    // The controller's input clock, in hertz.
    pub clock_hz: u32
    // The divisor, clock_hz / (16 * baud): its integer part, 1 to 65535,
    pub integer: u32
    // and its fraction in 64ths, 0 to 63.
    pub fraction: u32
    // The resulting baud rate, rounded to whole bits per second.
    pub baud: u32
}

divisors

Function · Source

The divisor from an input clock of clock_hz that comes closest to baud. It is exact to 1/128, so the rate is within 0.1 % of the request up to clock_hz / 128 (976 kbaud at 125 MHz), and within 0.8 % above; receivers tolerate about 2 %. InvalidInput above clock_hz / 16 (7.8 Mbaud at 125 MHz), the fastest possible, and below clock_hz / 1048560 (120 baud at 125 MHz), the slowest.

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

Parity

Enum · Source

The parity bit after each frame’s data bits.

pub enum Parity {
    // No parity bit, the usual setting.
    None,
    // A parity bit that makes the number of ones even.
    Even,
    // A parity bit that makes the number of ones odd.
    Odd
}

Controller

Struct · Source

A serial port on one PL011 with registers R, any hal.Registers. Implements the std/io Reader and Writer interfaces and their polling forms.

pub struct Controller<R: hal.Registers>: serial.Port + serial.PollPort {
    // Private implementation fields omitted.
}

Controller.new

Function · Source

Configure a controller fresh out of reset for 8N1 frames at the baud rate of divisors, computed from the clock that feeds it, and enable it.

pub fn new(registers: R, divisors: Divisors) -> Controller<R>

Controller.baud

Function · Source

The baud rate, in bits per second: the closest the controller can make to the requested one.

pub fn baud(&self) -> u32

Controller.set_poll_limit

Function · Source

Bound waits for output: status polls without progress before a write, flush, or a setting that waits for output gives up with TimedOut (Timeout for settings). NO_POLL_LIMIT waits as long as it takes.

pub fn set_poll_limit(&mut self, polls: u32)

Controller.set_read_poll_limit

Function · Source

Bound the wait for a read’s first byte the same way; reads wait as long as it takes at first.

pub fn set_read_poll_limit(&mut self, polls: u32)

Controller.set_baud

Function · Source

Change the baud rate. Waits until everything written is out first, so no byte goes out at the wrong rate. InvalidInput or Timeout leaves it unchanged.

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

Controller.set_format

Function · Source

Change the frame format: 5 to 8 data bits, the parity bit, and 1 or 2 stop bits. Modbus devices, for example, use 8E1: set_format(8, pl011.Parity.Even, 1). Waits like set_baud; InvalidInput or Timeout leaves the format unchanged.

pub fn set_format(&mut self, data_bits: u32, parity: Parity, stop_bits: u32) -> void!hal.Error

Controller.set_crlf

Function · Source

Translate newlines for a serial terminal: write each “\n” as “\r\n”, and read the carriage return that a terminal’s Enter key sends, alone or followed by “\n”, as one “\n”, so io.read_line ends at Enter. Off at first, so bytes pass unchanged, as binary protocols need.

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

Controller.set_flow_control

Function · Source

Turn hardware flow control on or off, once everything written is out. With cts, the transmitter sends only while the other end holds CTS low; with rts, the controller holds RTS low while its receive FIFO has room and raises it, asking the other end to pause, from 24 bytes on, so input is not lost while the program is busy. Both need the pins routed, which chip packages do for ports claimed with flow control. While CTS stays high nothing leaves, so waits for output end in TimedOut. Timeout, with flow control unchanged, if what was written does not get out.

pub fn set_flow_control(&mut self, cts: bool, rts: bool) -> void!hal.Error

Controller.listen

Function · Source

Raise the controller’s interrupt for these sources, such as RX_INTERRUPT | RX_TIMEOUT_INTERRUPT, in addition to those already listened to. Ports start with none.

pub fn listen(&mut self, sources: u32)

Controller.ignore

Function · Source

Stop raising the interrupt for these sources.

pub fn ignore(&mut self, sources: u32)

Controller.pending_interrupts

Function · Source

The listened-to sources that are pending now: what an interrupt handler has to serve.

pub fn pending_interrupts(&mut self) -> u32

Controller.clear_interrupts

Function · Source

Acknowledge sources whose condition does not end by itself, such as TX_INTERRUPT or ERROR_INTERRUPTS.

pub fn clear_interrupts(&mut self, sources: u32)

Controller.set_break

Function · Source

Hold the transmit line low, a break, from once everything written is out until set_break(false). A receiver sees a break when the line stays low for longer than a frame, so keep it on for at least two frame times (174 us at 115200 baud, 8N1); LIN and DMX, for example, start their frames with breaks. Timeout if what was written does not get out before a break starts.

pub fn set_break(&mut self, on: bool) -> void!hal.Error

Controller.set_loopback

Function · Source

Connect the transmitter to the receiver inside the controller, so reads return what was written and the TX pin stays idle. Meant for self-tests. Timeout if what was written does not get out.

pub fn set_loopback(&mut self, on: bool) -> void!hal.Error

Controller.write

Function · Source

Send bytes, waiting while the transmit FIFO is full. Returns once the last byte is queued; flush waits until it is sent. TimedOut, with the bytes queued before it in transferred, if the FIFO stays full for the poll limit.

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

Controller.poll_write

Function · Source

Queue as much of bytes as the transmit FIFO has room for, without waiting; Pending, with what was queued, once it is full.

pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error

Controller.flush

Function · Source

Wait until every byte written has left, stop bits included: before the other end may power down, or before restarting. TimedOut, with nothing transferred and nothing discarded, after the poll limit.

pub fn flush(&mut self) -> void!io.Error

Controller.poll_flush

Function · Source

flush without waiting: true once every byte written has left, false while some are still queued or being sent.

pub fn poll_flush(&mut self) -> bool!io.Error

Controller.read

Function · Source

Wait for the first byte, then return what has arrived, up to buffer.len. A serial port has no end of input, so a read never returns 0 bytes for a nonempty buffer. On a receive error, the bytes before it are in buffer[..transferred] and io.Error.code holds its bits; see FRAMING_ERROR. The next read continues after it.

pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error

Controller.poll_read

Function · Source

Return what the receive FIFO holds, up to buffer.len, without waiting: Pending, with nothing, while it is empty. Errors as for read.

pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error

Controller.dma_at

Function · Source

Receive into ring and send from output by DMA until the returned DmaPort is dropped; see DmaPort. data is the address of the controller’s data register as the channels see it, which chip packages know; Port.dma passes it. InvalidInput if ring holds no aligned block of MIN_RING bytes or output is empty, or if a channel cannot serve this controller; Busy if a channel is still running.

pub fn dma_at(&mut self, data: usize, rx: &mut dyn hal.DmaChannel, ring: &mut[u8], tx: &mut dyn hal.DmaChannel, output: &mut[u8]) -> DmaPort!hal.Error from(self, rx, ring, tx, output)

Controller.release

Function · Source

Wait until everything written is out, within the poll limit, disable the controller, and give back its registers. Output still stuck after the poll limit is dropped.

pub fn release(self) -> R

MIN_RING

Constant · Source

The smallest receive ring a DmaPort uses: the receive FIFO’s size.

pub const MIN_RING: usize = 32

DmaPort

Struct · Source

A serial port that receives into a ring buffer and sends from an output buffer by DMA, from Port.dma(rx, ring, tx, output). It implements the std/io Reader and Writer protocols like Port, with two differences:

  • Input is kept in the ring, not just the 32-byte FIFO, so the program reads at its own pace: a 1 KiB ring holds 89 ms of input at 115200 baud. rx moves each byte into the ring as it arrives, round and round; bytes the program has not read when the ring comes round again are lost, and the next read reports OVERRUN.
  • A write copies its bytes into output and returns once tx is sending them, waiting only while the previous write is still going out, so printing hardly ever waits for the line.

The ring is the largest block within ring whose size is a power of two and whose address is a multiple of its size, as the channel needs: a static buffer with @align(N) and N bytes gives all N, any other buffer at least a quarter of its length (ring_size() tells). Bytes with framing or parity errors, and breaks, arrive in the ring like others; a read reports the error, with the code bits of FRAMING_ERROR and the rest, after the bytes it returns, without telling which byte it was.

A task waits for input with the executor: rx’s signal is raised only when its transfer ends, so poll on a ticker, or listen for RX_TIMEOUT_INTERRUPT and RX_INTERRUPT as with a polled port. Dropping the DmaPort stops both channels and hands the port back; input still in the ring is lost and output not yet sent is cut short.

pub struct DmaPort: serial.Port + serial.PollPort {
    // Private implementation fields omitted.
}

DmaPort.ring_size

Function · Source

The ring’s size in bytes: how much input waits for the program.

pub fn ring_size(&self) -> usize

DmaPort.available

Function · Source

The bytes received and not yet read, up to the ring’s size.

pub fn available(&mut self) -> usize

DmaPort.read

Function · Source

Wait for the first byte, then return what has arrived, up to buffer.len; errors as for poll_read. The read poll limit bounds the wait as on Port.

pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error

DmaPort.poll_read

Function · Source

Return what the ring holds, up to buffer.len, without waiting: Pending, with nothing, while it is empty. An error has kind Other and the bits of FRAMING_ERROR, PARITY_ERROR, BREAK, and OVERRUN in its code, after the bytes before it in buffer[..transferred]; OVERRUN here means the ring came round over unread bytes, which are dropped.

pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error

DmaPort.write

Function · Source

Send bytes: copy them into the output buffer, chunk by chunk, each once the previous one has gone into the transmit FIFO, and return when the last chunk is on its way; flush waits until it has left. TimedOut, with the bytes handed over before it, if a chunk makes no progress for the poll limit.

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

DmaPort.poll_write

Function · Source

Hand over as much of bytes as the output buffer takes if the previous write is out of it, without waiting; Pending, with what was handed over, otherwise.

pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error

DmaPort.poll_flush

Function · Source

Wait until everything written has left; TimedOut after the poll limit, as on Port. flush without waiting: true once everything written has left the output buffer and the transmitter.

pub fn poll_flush(&mut self) -> bool!io.Error

DmaPort.flush

Function · Source

pub fn flush(&mut self) -> void!io.Error

DmaPort.set_crlf

Function · Source

Translate newlines, as Port.set_crlf does.

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

DmaPort.set_poll_limit

Function · Source

Bound waits for output, and for a read’s first byte, in polls, as on Port.

pub fn set_poll_limit(&mut self, polls: u32)

DmaPort.set_read_poll_limit

Function · Source

pub fn set_read_poll_limit(&mut self, polls: u32)

DmaPort.listen

Function · Source

Interrupts, as on Port: with RX_TIMEOUT_INTERRUPT, a pause in the input raises the port’s interrupt, so a task can wait for a message to end. Reading the ring does not end that condition; the channel emptying the FIFO does.

pub fn listen(&mut self, sources: u32)

DmaPort.ignore

Function · Source

pub fn ignore(&mut self, sources: u32)

DmaPort.pending_interrupts

Function · Source

pub fn pending_interrupts(&mut self) -> u32

DmaPort.clear_interrupts

Function · Source

pub fn clear_interrupts(&mut self, sources: u32)

send

Function · Source

Send bytes through the PL011 with registers registers, configured by its owner, and wait until they are out. Does nothing if the transmitter is off. This is for panic hooks, which run while the owner is suspended for good; everything else goes through a Controller.

pub fn send<R: hal.Registers>(registers: &mut R, bytes: &[u8])

Port

Struct · Source

A PL011 on the chip, as chip packages hand it to applications. It implements the std/io Reader and Writer protocols like Controller but keeps the register block: RegisterBlock trusts its owner with every offset, which only the driver may be.

pub struct Port: serial.Port + serial.PollPort {
    // Private implementation fields omitted.
}

Port.at

Function · Source

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

pub unsafe fn at(base: usize, divisors: Divisors) -> Port

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

Port.write

Function · Source

Send bytes, waiting while the transmit FIFO is full. Returns once the last byte is queued; flush waits until it is sent. TimedOut after the poll limit.

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

Port.poll_write

Function · Source

Queue what fits in the transmit FIFO without waiting; Pending once it is full.

pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error

Port.flush

Function · Source

Wait until every byte written has left; TimedOut after the poll limit.

pub fn flush(&mut self) -> void!io.Error

Port.poll_flush

Function · Source

pub fn poll_flush(&mut self) -> bool!io.Error

Port.set_poll_limit

Function · Source

Bound waits for output, in status polls; see Controller.

pub fn set_poll_limit(&mut self, polls: u32)

Port.set_read_poll_limit

Function · Source

Bound the wait for a read’s first byte; unbounded at first.

pub fn set_read_poll_limit(&mut self, polls: u32)

Port.read

Function · Source

Wait for the first byte, then return what has arrived. A receive error fails with its bits in io.Error.code; see FRAMING_ERROR.

pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error

Port.poll_read

Function · Source

Return what has arrived without waiting; Pending while nothing has.

pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error

Port.baud

Function · Source

The baud rate: the closest the controller can make to the requested one.

pub fn baud(&self) -> u32

Port.set_baud

Function · Source

Change the baud rate, once everything written is out.

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

Port.set_format

Function · Source

Change the frame format: 5 to 8 data bits, parity, and 1 or 2 stop bits.

pub fn set_format(&mut self, data_bits: u32, parity: Parity, stop_bits: u32) -> void!hal.Error

Port.set_crlf

Function · Source

Translate newlines for a serial terminal: “\n” goes out as “\r\n”, and Enter reads as “\n”.

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

Port.set_flow_control

Function · Source

Turn hardware flow control on or off: the transmitter waits for CTS, and RTS asks the other end to pause while the receive FIFO is nearly full. Needs a port claimed with its flow control pins.

pub fn set_flow_control(&mut self, cts: bool, rts: bool) -> void!hal.Error

Port.set_break

Function · Source

Hold the transmit line low, a break, once everything written is out, until set_break(false).

pub fn set_break(&mut self, on: bool) -> void!hal.Error

Port.set_loopback

Function · Source

Loop the transmitter back to the receiver inside the chip, for self-tests: reads return what was written.

pub fn set_loopback(&mut self, on: bool) -> void!hal.Error

Port.listen

Function · Source

Raise the port’s interrupt for these sources, such as RX_INTERRUPT | RX_TIMEOUT_INTERRUPT; see Controller.listen.

pub fn listen(&mut self, sources: u32)

Port.ignore

Function · Source

Stop raising the interrupt for these sources.

pub fn ignore(&mut self, sources: u32)

Port.pending_interrupts

Function · Source

The listened-to sources pending now.

pub fn pending_interrupts(&mut self) -> u32

Port.clear_interrupts

Function · Source

Acknowledge TX_INTERRUPT or ERROR_INTERRUPTS.

pub fn clear_interrupts(&mut self, sources: u32)

Port.dma

Function · Source

Receive into ring and send from output by DMA, with channels rx and tx, until the returned DmaPort is dropped; see DmaPort. InvalidInput if ring holds no aligned block of MIN_RING bytes, output is empty, or a channel cannot serve this port.

pub fn dma(&mut self, rx: &mut dyn hal.DmaChannel, ring: &mut[u8], tx: &mut dyn hal.DmaChannel, output: &mut[u8]) -> DmaPort!hal.Error from(self, rx, ring, tx, output)

Port.release

Function · Source

Wait until everything written is out, within the poll limit, disable the controller, and return its base address, for the chip package to take the port back.

pub fn release(self) -> usize

Search every guide, reference page, and API declaration.