Struct Descriptor 

pub struct Descriptor {
    pub header: DescriptorHeader,
    pub write_ptr: u16,
    pub read_ptr: u16,
    pub capacity: u16,
    pub flags: Flags,
    /* private fields */
}

In-memory mirror of the shared CDBG descriptor.

#[repr(C)] keeps the field order matching the on-wire layout documented in the module header, but reads/writes still go through the explicit offset constants below (via volatile helpers) rather than relying on struct layout.

Fields

header: DescriptorHeader

Magic + version stamp shared by all Consortium descriptors.

write_ptr: u16

Writer-owned cursor: byte offset where the next frame will be written.

read_ptr: u16

Reader-owned cursor: byte offset of the next frame to be read. read_ptr == write_ptr means the ring is empty.

capacity: u16

Total byte length of the shared region (header + data). Acts as the wrap-around bound for the circular buffer; usable data is [DATA_START, capacity).

flags: Flags

Writer-owned status flags (e.g. overflow).

Implementations

impl Descriptor

pub const fn new(capacity: u16) -> Self

Builds a fresh descriptor for a region of capacity total bytes, with both cursors parked at DATA_START (empty ring) and no flags set.

pub fn check(&self) -> bool

Returns true if the descriptor header has the expected magic and version.

pub unsafe fn from_raw_ptr(ptr: *const u8) -> Self

Reads a Descriptor from shared memory at ptr.

Safety

ptr must point to a valid, readable shared-memory region of at least DESCRIPTOR_SIZE bytes with consistent volatile layout.

pub unsafe fn write_to_raw_ptr(&self, ptr: *mut u8)

Writes this descriptor to shared memory at ptr.

Safety

ptr must point to a valid, writable shared-memory region of at least DESCRIPTOR_SIZE bytes.

pub unsafe fn try_read_frame( &mut self, base: *mut u8, buf: &mut [u8], ) -> ReadOutcome

Copies the next available frame’s payload into buf and consumes it.

The one read path: read_one_frame, the host reader, and RingReader all go through it. It allocates nothing, so it serves no_std readers too.

A frame whose payload is longer than buf is left in the ring, unconsumed, and reported as ReadOutcome::TooSmall so the caller can retry with a larger buffer; one of MAX_FRAME_LEN bytes always fits.

Safety

base must point to the start of the shared-memory region owning this descriptor, valid for at least self.capacity bytes.

pub unsafe fn read_one_frame(&mut self, base: *mut u8) -> Option<Vec<u8>>

Reads the next available defmt frame from the circular buffer, returning its payload.

Returns None if no frame is available or if the current frame header is invalid.

Safety

base must point to the start of the shared-memory region owning this descriptor, valid for at least self.capacity bytes.

pub unsafe fn read_bulk_frames(&mut self, base: *mut u8) -> Vec<Vec<u8>>

Drains all available defmt frames from the circular buffer, returning them as a Vec.

Safety

Same requirements as read_one_frame: base must be valid for at least self.capacity bytes.

pub unsafe fn write_one_frame(&mut self, base: *mut u8, frame: &[u8]) -> bool

Writes a single defmt frame into the circular buffer.

Returns true on success; returns false and sets the Overflow flag if the frame does not fit without overwriting unread data.

Safety

base must point to the start of the shared-memory region owning this descriptor, valid for at least self.capacity bytes.