API referencestd/embedded

std/embedded/chip/rp_usb

Public declarations, types, methods, and source contracts for std/embedded/chip/rp_usb.

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/chip/rp_usb"

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
executor std/embedded/executor rp_usb.dodo
hal std/embedded/hal rp_usb.dodo
io std/io rp_usb.dodo
mem core/mem rp_usb.dodo
ptr core/ptr rp_usb.dodo
rp_pins std/embedded/chip/rp_pins rp_usb.dodo
serial std/embedded/hal/serial rp_usb.dodo

PACKET_SIZE

Constant · Source

pub const PACKET_SIZE: usize = 64

Identity

Struct · Source

The device’s identity on the bus: the vendor and product IDs a host matches drivers and tools against, and the manufacturer and product strings it shows. The IDs name the device and its firmware, not the library it was built with.

pub struct Identity {
    pub vendor_id: u16
    pub product_id: u16
    // ASCII, cut at MAX_STRING_LENGTH bytes.
    pub manufacturer: &str
    pub product: &str
}

DEFAULT_VENDOR_ID

Constant · Source

The default identity’s IDs, for development: Raspberry Pi’s vendor ID with the product ID of the Pico SDK’s USB serial port (CDC UART). Hosts and tools take a board using them for a Pico running Pico SDK firmware, which the device behaves like, and dodo run finds it by them to restart it into the bootloader. A product distributed with its own USB identity uses a vendor ID its maker owns, or a product ID assigned to it under someone else’s, never another product ID under Raspberry Pi’s.

pub const DEFAULT_VENDOR_ID: u16 = 0x2E8A

DEFAULT_PRODUCT_ID

Constant · Source

pub const DEFAULT_PRODUCT_ID: u16 = 0x000A

DEFAULT_MANUFACTURER

Constant · Source

pub const DEFAULT_MANUFACTURER: &str = "Dodo"

MAX_STRING_LENGTH

Constant · Source

The longest manufacturer and product strings, in bytes of ASCII.

pub const MAX_STRING_LENGTH: usize = 32

default_identity

Function · Source

The default identity, with the default IDs and manufacturer, and product as the product string.

pub fn default_identity(product: &str) -> Identity

TX_CAPACITY

Constant · Source

Queue sizes. Output is kept while no terminal has the port open, up to TX_CAPACITY bytes, and input until the program reads it: the host waits while RX_CAPACITY - PACKET_SIZE bytes are unread.

pub const TX_CAPACITY: usize = 1024

RX_CAPACITY

Constant · Source

pub const RX_CAPACITY: usize = 256

BOOTLOADER_BAUD

Constant · Source

The baud rate that, set by the host, restarts the board into its USB bootloader: the “1200 baud touch” of the Pico SDK and Arduino.

pub const BOOTLOADER_BAUD: u32 = 1200

DTR

Constant · Source

The control lines a terminal sets (SET_CONTROL_LINE_STATE).

pub const DTR: u32 = 1 << 0

RTS

Constant · Source

pub const RTS: u32 = 1 << 1

RECEIVED

Constant · Source

What serve did, one bit each: bytes arrived, bytes left, the host configured or deconfigured the device, changed DTR or RTS, suspended or resumed it, and a 1200-baud line coding asks for the bootloader.

pub const RECEIVED: u32 = 1 << 0

SENT

Constant · Source

pub const SENT: u32 = 1 << 1

LINE_CHANGED

Constant · Source

pub const LINE_CHANGED: u32 = 1 << 2

BOOTLOADER_REQUESTED

Constant · Source

pub const BOOTLOADER_REQUESTED: u32 = 1 << 3

Device

Struct · Source

The device over controller registers R. See the package comment.

pub struct Device<R: hal.Registers> {
    // Private implementation fields omitted.
}

Device.new

Function · Source

A stopped device on controller registers registers and DPRAM ram. Newline translation is on: see set_crlf.

pub fn new(registers: R, ram: R) -> Device<R>

Device.start

Function · Source

Power the controller up as a device with identity and connect to the host, which then enumerates it. The controller must be out of reset with clk_usb at 48 MHz.

pub fn start(&mut self, identity: Identity)

Device.stop

Function · Source

Disconnect from the host and power the controller down. Queued output is dropped.

pub fn stop(&mut self)

Device.serve

Function · Source

Answer the host: handle finished buffers, a SETUP packet, a bus reset, and suspension, and keep both bulk endpoints busy. Returns what happened, as RECEIVED, SENT, LINE_CHANGED, and BOOTLOADER_REQUESTED bits. Run it from the controller’s interrupt, or poll it.

pub fn serve(&mut self) -> u32

Device.queue

Function · Source

Queue the start of bytes for the host, as far as there is room, and return how many were queued. With newline translation, a “\n” goes out as “\r\n” and needs room for both.

pub fn queue(&mut self, bytes: &[u8]) -> usize

Device.take

Function · Source

Move received bytes into buffer and return how many. With newline translation, the CR that Enter sends, alone or followed by LF, reads as one “\n”.

pub fn take(&mut self, buffer: &mut[u8]) -> usize

Device.make_room

Function · Source

Drop the oldest queued output until count bytes fit, for a message that must go out, such as a panic report.

pub fn make_room(&mut self, count: usize)

Device.set_crlf

Function · Source

Write “\n” as “\r\n” and read Enter as “\n”, for terminals. On at first; turn it off for binary data.

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

Device.set_bootloader_reset

Function · Source

Whether a 1200-baud line coding restarts the board into its bootloader; on at first.

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

Device.is_configured

Function · Source

The host has configured the device: it is enumerated, and the port exists on the host.

pub fn is_configured(&self) -> bool

Device.is_connected

Function · Source

A program on the host has the port open: configured, with DTR set, as terminals do while open.

pub fn is_connected(&self) -> bool

Device.line_state

Function · Source

DTR and RTS as the host last set them.

pub fn line_state(&self) -> u32

Device.baud

Function · Source

The baud rate the host last set. It changes nothing on USB, but tells a bridge to another serial port what to use.

pub fn baud(&self) -> u32

Device.unsent

Function · Source

Bytes queued for the host and not yet taken by it.

pub fn unsent(&self) -> usize

Device.room

Function · Source

Room for output, in bytes.

pub fn room(&self) -> usize

Device.available

Function · Source

Received bytes not yet taken.

pub fn available(&self) -> usize

Device.frame

Function · Source

The frame number of the host’s last start-of-frame, 0 to 2047, counting milliseconds while the bus runs.

pub fn frame(&mut self) -> u32

Device.release

Function · Source

Give back the register blocks, after stop.

pub fn release(self) -> (R, R)

WRITE_TIMEOUT_FRAMES

Constant · Source

Frames (milliseconds) a write waits for the host to take output from a full queue before it drops the rest, and status polls as a bound when frames stop.

pub const WRITE_TIMEOUT_FRAMES: u32 = 100

open

Function · Source

Start the device on the controller at registers with its DPRAM at ram, announcing itself with identity, and return its port. Writes queue at once; the host enumerates the device within a second of connection, after which a terminal can open it. bootloader restarts the chip into its USB bootloader. The caller enables USBCTRL_IRQ in the NVIC. SAFETY: the controller must be out of reset with clk_usb at 48 MHz, no port may be open, and nothing else may use the controller.

pub unsafe fn open(registers: usize, ram: usize, identity: Identity, bootloader: fn()) -> Serial

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

close

Function · Source

Disconnect and stop the device of serial. The caller disables USBCTRL_IRQ and holds the controller in reset afterwards.

pub fn close(serial: Serial)

report_panic

Function · Source

Queue a panic report, as rp_pins.report_panic writes it, and wait until the host has taken it, the port is closed, or PANIC_TIMEOUT_FRAMES pass. Older output makes room if needed. Does nothing without an open port. SAFETY: check and file must be NUL-terminated, and interrupts must be masked for good: the caller halts or resets afterwards.

pub unsafe fn report_panic(check: *const u8, file: *const u8, line: u32, column: u32)

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

idle_after_panic

Function · Source

Keep serving an open port forever with interrupts masked, after a panic: a terminal opened later still receives the report, and a host can still restart the board into its bootloader. Returns at once without a port. SAFETY: interrupts must be masked for good, as in a panic hook.

pub unsafe fn idle_after_panic()

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

Serial

Struct · Source

The USB serial port, as chip packages hand it out. Implements the std/io Reader and Writer protocols, so std/fmt prints to it. Every method is safe to call at any time; the interrupt handler serves the host in between.

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

Serial.write

Function · Source

Queue bytes for the host and return once they are queued. While no terminal has the port open, output is kept up to TX_CAPACITY bytes, for the terminal to receive when it opens it, and the rest is dropped. While one has it open, a full queue waits for the host, and output the host does not take within WRITE_TIMEOUT_FRAMES ms is dropped, so printing never stops the program. Never fails.

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

Serial.poll_write

Function · Source

Queue what fits without waiting; Pending, with what was queued, once the queue is full.

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

Serial.poll_flush

Function · Source

flush without waiting: true once the host has taken everything written, or no terminal has the port open. Never fails.

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

Serial.flush

Function · Source

Wait until the host has taken everything written, while a terminal has the port open and the host keeps taking output; as write, it gives up after WRITE_TIMEOUT_FRAMES ms without progress. Never fails.

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

Serial.read

Function · Source

Wait for the first byte, then return what has arrived, up to buffer.len. A USB serial port never reaches end of input.

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

Serial.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

Serial.is_connected

Function · Source

Whether a program on the host has the port open (DTR set), so that what is written now is read now.

pub fn is_connected(&self) -> bool

Serial.is_configured

Function · Source

Whether the host has enumerated and configured the device.

pub fn is_configured(&self) -> bool

Serial.line_state

Function · Source

DTR and RTS, as the host last set them.

pub fn line_state(&self) -> u32

Serial.baud

Function · Source

The baud rate the host last set; 115200 until it sets one.

pub fn baud(&self) -> u32

Serial.available

Function · Source

Received bytes waiting to be read.

pub fn available(&self) -> usize

Serial.set_crlf

Function · Source

Write “\n” as “\r\n” and read Enter as “\n”, for terminals. On at first; turn it off for binary data.

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

Serial.set_bootloader_reset

Function · Source

Whether the host setting 1200 baud restarts the board into its bootloader, as dodo run does; on at first.

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

Serial.set_signal

Function · Source

Raise signal from the interrupt whenever something happens on the port: bytes arrive, output leaves, or the host connects, opens, closes, or suspends it. A task that takes the signal and then reads with poll_read is woken by input; see std/embedded/executor.

pub fn set_signal(&mut self, signal: &executor.Signal)

Serial.clear_signal

Function · Source

Stop raising the signal.

pub fn clear_signal(&mut self)

Search every guide, reference page, and API declaration.