Struct RingBufferedUartRx 

pub struct RingBufferedUartRx<'d, W: UsartWord = u8> { /* private fields */ }

Rx-only Ring-buffered UART Driver

Created with UartRx::into_ring_buffered

Notes on ‘waiting for words’

The read(buf) (but not read()) function may need to wait for words to arrive, if the ring buffer does not contain enough words to fill the buffer passed by the caller of the function, or is empty.

Waiting for words operates in one of three modes, depending on the behavior of the sender, the size of the buffer passed to the function, and the configuration:

• If the sender sends intermittently, the ‘idle line’ condition will be detected when the sender stops, and any words in the ring buffer will be returned. If there are no words in the buffer, the check will be repeated each time the ‘idle line’ condition is detected, so if the sender sends just a single word, it will be returned once the ‘idle line’ condition is detected.

• If the sender sends continuously, the call will wait until the DMA controller indicates that it has written to either the middle word or last word of the ring buffer (‘half transfer’ or ‘transfer complete’, respectively). This does not indicate the buffer is half-full or full, though, because the DMA controller does not detect those conditions; it sends an interrupt when those specific buffer addresses have been written.

• If eager_reads is enabled in config, the UART interrupt is enabled on all data reception and the call will only wait for at least one word to be available before returning.

In the first two cases this will result in variable latency due to the buffering effect. For example, if the baudrate is 2400 bps, and the configuration is 8 data bits (so each word is one byte), no parity bit, and one stop bit, then a byte will be received every ~4.16ms. If the ring buffer is 32 bytes, then a ‘wait for bytes’ delay may have to wait for 16 bytes in the worst case, resulting in a delay (latency) of ~62.46ms for the first byte in the ring buffer. If the sender sends only 6 bytes and then stops, but the buffer was empty when the read function was called, then those bytes may not be returned until ~24.96ms after the first byte was received (time for 5 additional bytes plus the ‘idle frame’ which triggers the ‘idle line’ condition).

Applications subject to this latency must be careful if they also apply timeouts during reception, as it may appear (to them) that the sender has stopped sending when it did not. In the example above, a 50ms timeout (12 bytes at 2400bps) might seem to be reasonable to detect that the sender has stopped sending, but would be falsely triggered in the worst-case buffer delay scenario.

Note: Enabling eager_reads with RingBufferedUartRx will enable an UART RXNE interrupt, which will cause an interrupt to occur on every received word. The data is still copied using DMA, but there is nevertheless additional processing overhead for each word.

Implementations

impl<'d, W: UsartWord> RingBufferedUartRx<'d, W>

pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError>

Reconfigure the driver

pub fn start_uart(&mut self)

Configure and start the DMA backed UART receiver

Note: This is also done automatically by the read functions if required.

pub fn clear(&mut self)

Clears ring buffer.

pub async fn read(&mut self, buf: &mut [W]) -> Result<usize, Error>

Read words that are available in the ring buffer, or wait for words to become available and return them. Returns the number of words read into buf.

Background reception is started if necessary (if start_uart() had not previously been called, or if an error was detected which caused background reception to be stopped).

Background reception is terminated when an error is returned. It must be started again by calling start_uart() or by calling a read function again.

pub fn set_baudrate(&self, baudrate: u32) -> Result<(), ConfigError>

Set baudrate

Trait Implementations

impl<W: UsartWord> Drop for RingBufferedUartRx<'_, W>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<W: UsartWord> ErrorType for RingBufferedUartRx<'_, W>

type Error = Error

Error type of all the IO operations on this type.

impl<W: UsartWord> ErrorType for RingBufferedUartRx<'_, W>

type Error = Error

Error type

impl Read for RingBufferedUartRx<'_, u8>

async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read.

async fn read_exact( &mut self, buf: &mut [u8], ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf.

impl Read for RingBufferedUartRx<'_, u8>

fn read(&mut self) -> Result<u8, Self::Error>

Reads a single word from the serial interface

impl<W: UsartWord> ReadReady for RingBufferedUartRx<'_, W>

fn read_ready(&mut self) -> Result<bool, Self::Error>

Get whether the reader is ready for immediately reading.

impl<'d, W: UsartWord> SetConfig for RingBufferedUartRx<'d, W>

type Config = Config

The configuration type used by this driver.

type ConfigError = ConfigError

The error type that can occur if set_config fails.

fn set_config(&mut self, config: &Self::Config) -> Result<(), Self::ConfigError>

Set the configuration of the driver.