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, andclear_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_hzthat comes closest tobaud. 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_lineends 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; withrts, 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;flushwaits until it is sent. TimedOut, with the bytes queued before it intransferred, 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
bytesas 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
flushwithout 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 forread.
pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error
Controller.dma_at
Function · Source
Receive into
ringand send fromoutputby DMA until the returned DmaPort is dropped; see DmaPort.datais the address of the controller’s data register as the channels see it, which chip packages know;Port.dmapasses it. InvalidInput ifringholds no aligned block of MIN_RING bytes oroutputis 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.
rxmoves 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
outputand returns oncetxis 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
ringwhose 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 forpoll_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;flushwaits 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
bytesas 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.
flushwithout 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
bytesthrough the PL011 with registersregisters, 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:
RegisterBlocktrusts 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
basea 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;flushwaits 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
ringand send fromoutputby DMA, with channelsrxandtx, until the returned DmaPort is dropped; see DmaPort. InvalidInput ifringholds no aligned block of MIN_RING bytes,outputis 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