Detailed Description

template<unsigned SIZE = SATCAT5_SAMV71_UART_BUFFSIZE>
class satcat5::sam::UsartSamv71Static< SIZE >

UsartSamv71 variant with statically-allocated TX and RX buffers; most users should instantiate this instead of UsartSamv71.

Optional template parameter specifies buffer sizes.

TODO: Benefit of disjoint BufferedIO and DMA buffer sizes?

io::BufferedIO interface for the SAMV71 USART and UART peripherals. UART (not USART) peripherals are also supported by this class due to a shared register map between the two. Hardware flow control (RTS/CTS) is not supported for UART peripherals.

Note that this does NOT establish the SAMV71 I/O mux, this should be done externally. Note that support for RTS and/or CTS can be configured independently.

A configurable polling interval is available in the constructor. The DMA controller only raises interrupts when the buffers are full, so some periodic checking of buffer occupancy is required. Less frequent polling is appropriate for low-rate latency-insensitive tasks, and more frequent polling is appropriate for higher throughput UARTs. Setting the polling interval to 0 enables continuous polling via poll::Always to reduce receive latency to the minimum supported by SatCat5.

Most users should instantiate sam::UsartSamv71Static instead of this to perform all stack buffer allocation.

This class supports but does not require interrupts, which are triggered if the receive DMA is full (about to overflow) or the transmit DMA is empty (finished sending a frame). This helps allow for lower polling intervals, but must be manually set up in an external file such as main.cc. The single DMA controller interrupt MUST be named exactly void XDMAC_Handler() and service all system UsartSamv71 instances:

satcat5::sam::UsartSamv71<...> uart0(...);
satcat5::sam::UsartSamv71<...> uart1(...);
 
void XDMAC_Handler() {
    irq_controller.irq_handler(&uart0);
    irq_controller.irq_handler(&uart1);
}
 
int main(void) {
    // ...
    NVIC_DisableIRQ(XDMAC_IRQn);
    NVIC_ClearPendingIRQ(XDMAC_IRQn);
    NVIC_SetPriority(XDMAC_IRQn, 4);
    NVIC_EnableIRQ(XDMAC_IRQn);
    // ...
    // Start servicing SatCat5 core loop
}

Definition at line 187 of file sam_usart.h.

#include <sam_usart.h>

Inheritance diagram for satcat5::sam::UsartSamv71Static< SIZE >:

[legend]

Collaboration diagram for satcat5::sam::UsartSamv71Static< SIZE >:

[legend]

Public Member Functions
	UsartSamv71Static (Usart *usart, unsigned baud_hz, unsigned poll_ms, bool fc_on=false)
	Constructor for an ASF3 USART with built-in buffers. More...

void	configure (unsigned baud_hz, bool rts_en, bool cts_en)
	Set baud rate and RTS/CTS enable. More...

void	configure (unsigned baud_hz, bool fc_on=false)
	Alias for backwards compatibility (deprecated).

void	set_callback (satcat5::io::EventListener *callback) override
	Update registered callback for data_rcvd() events. More...

unsigned	get_read_ready () const override
	How many bytes can be read without blocking? More...

bool	read_bytes (unsigned nbytes, void *dst) override
	Read 0 or more bytes into a buffer. More...

bool	read_consume (unsigned nbytes) override
	Read and discard 0 or more bytes. More...

void	read_finalize () override
	Consume any remaining bytes in this frame, if applicable. More...

u8	read_u8 ()
	One of many functions for reading integer/floating point values, see details. More...

unsigned	read_str (unsigned dst_size, char *dst)
	Safely read a null-terminated input string. More...

template<class T >
bool	read_obj (T &t)
	Templated wrapper for any object with the following method: `bool read_from(satcat5::io::Readable* rd);`

unsigned	copy_to (satcat5::io::Writeable *dst)
	Copy data to a Writeable object, without finalizing. More...

bool	copy_and_finalize (satcat5::io::Writeable *dst, satcat5::io::CopyMode mode=CopyMode::PACKET)
	Copy data to a Writeable object, then finalize. More...

void	request_poll ()
	Call this method to request polling at a later time. More...

void	request_cancel ()
	Call this method to cancel a previous request_poll().

unsigned	get_write_space () const override
	How many bytes can be written without blocking? More...

void	write_abort () override
	If possible, abort the current partially-written packet. More...

void	write_bytes (unsigned nbytes, const void *src) override
	Write 0 or more bytes from a buffer. More...

bool	write_finalize () override
	Mark end of frame and release temporary working data. More...

void	write_u8 (u8 data)
	One of many functions for writing integer/floating point values, see details. More...

void	write_str (const char *str)
	Write the contents of a null-terminated string. More...

template<class T >
void	write_obj (const T &obj)
	Templated wrapper for any object with the following method: `void write_to(satcat5::io::Writeable* wr) const;`

void	timer_once (unsigned msec)
	Configure a one-time notification after X milliseconds.

void	timer_every (unsigned msec)
	Configure a repeating notification every X milliseconds.

void	timer_stop ()
	Stop all future notifications.

unsigned	timer_interval () const
	Accessor for recurring timer interval, if one is set.

unsigned	timer_remaining () const
	Accessor for time to next event, if one is set.

Static Public Member Functions
static unsigned	count_ondemand ()
	Count queued objects of this type (i.e., non-idle).

static unsigned	count_timer ()
	Count all objects of this type, including idle timers.

static unsigned	count_always ()
	Count active objects of this type.

Public Attributes
const char *const	m_label
	Human-readable label, for debugging.

const int	m_irq_idx
	IRQ index for this interrupt handler.

Protected Member Functions
void	data_rcvd (satcat5::io::Readable *src) override
	Immediately transfer incoming TX data to the DMA engine.

void	irq_event () override
	IRQ indicates the RX DMA is full or the TX DMA is empty.

u8 *	get_rxdma_buff ()
	Get the RX buffer the DMA is currently writing to.

void	poll_tx_dma ()
	Poll the RX DMA engine for new data received.

void	poll_rx_dma ()
	Poll the TX DMA engine for unsent data to transmit.

void	configure_xdmac (u32 tx_dma_ch, u32 rx_dma_ch)
	Initial setup of the TX/RX DMA controllers.

u8	read_next () override
	Read the next byte from the underlying buffer or device. More...

void	read_underflow () override
	Optional error handling for read underflow. More...

void	read_src (satcat5::io::Readable *src)
	Children may reset the source object as needed.

void	read_notify ()
	Attempt notification by calling `m_callback->data_rcvd()`. More...

void	write_next (u8 data) override
	Write the next byte to the underlying buffer or device. More...

void	write_overflow () override
	Optional error handling for write overflow. More...

void	write_dst (satcat5::io::Writeable *dst)

virtual void	data_unlink (satcat5::io::Readable *src)
	Unlink this EventListener from the designated source, because the designated Readable object is being destroyed. More...

void	poll_register ()
	Register this pollable object, called by the constructor.

void	poll_unregister ()
	Unregister this pollable object, called by the destructor.


void	timer_event () override
	The user may configure either continuous polling or timer-based polling; either should perform the same task of servicing both the RX and TX DMAs.

void	poll_always () override
	The user may configure either continuous polling or timer-based polling; either should perform the same task of servicing both the RX and TX DMAs.


void	rts_high ()
	Drive the RTS signal high/low if flow-control is on.

void	rts_low ()
	Drive the RTS signal high/low if flow-control is on.

Protected Attributes
satcat5::io::PacketBuffer	m_tx
	Transmit data (user writes, child reads)

satcat5::io::PacketBuffer	m_rx
	Receive data (user reads, child writes)

friend	WriteableRedirect

friend	LimitedWrite

friend	WriteableBroadcast

u32	m_max_irqtime
	Statistics tracking for time consumed by this interrupt.

Private Member Functions
void	poll_demand ()
	Event handler for on-demand polling.

void	query (unsigned elapsed_msec)

Private Attributes
u8	m_txbuff [SIZE]

u8	m_rxbuff [SIZE]

u8	m_rxdma0 [SIZE]

u8	m_rxdma1 [SIZE]

Usart *	m_usart

unsigned	m_txdma_nbytes

const unsigned	m_rxdma_nbytes

unsigned	m_rxdma_buffidx

bool	m_rts_en

bool	m_cts_en

u8	m_tx_dma_ch

u8	m_rx_dma_ch

satcat5::io::Readable *	m_src

satcat5::io::EventListener *	m_callback
	Pointer to the callback object, or NULL. More...

satcat5::poll::OnDemand *	m_next

bool	m_idle

satcat5::io::Writeable *	m_dst

unsigned	m_trem

unsigned	m_tnext

Constructor & Destructor Documentation

◆ UsartSamv71Static()

template<unsigned SIZE = SATCAT5_SAMV71_UART_BUFFSIZE>

satcat5::sam::UsartSamv71Static< SIZE >::UsartSamv71Static	(	Usart *	usart,
		unsigned	baud_hz,
		unsigned	poll_ms,
		bool	fc_on = `false`
	)

inline

Constructor for an ASF3 USART with built-in buffers.

See also: UsartSamv71::UsartSamv71().

Parameters

usart	Pointer to (baseaddr of) UART/USART peripheral.
baud_hz	Baud rate for the serial line, in Hz.
poll_ms	Polling rate for new data in ms, or = 0 for continuous polling via poll::Always.
fc_on	Use hardware flow control (RTS/CTS), default off.

Definition at line 197 of file sam_usart.h.

Member Function Documentation

◆ configure()

void UsartSamv71::configure	(	unsigned	baud_hz,
		bool	rts_en,
		bool	cts_en
	)

inherited

Set baud rate and RTS/CTS enable.

Always set to 8 bit length, no parity, 1 stop bit.

Definition at line 126 of file sam_usart.cc.

◆ copy_and_finalize()

bool Readable::copy_and_finalize	(	satcat5::io::Writeable *	dst,
		satcat5::io::CopyMode	mode = `CopyMode::PACKET`
	)

inherited

Copy data to a Writeable object, then finalize.

As copy_to(), but also calls read_finalize() and/or write_finalize() depending on the input/output mode.

In packet mode (the default), call both read_finalize() and write_finalize() if the operation copies all available data. Use this mode whenever the input is packetized.

In byte-stream mode, call write_finalize() if the operation copies any data, but never call read_finalize(). Use this mode for inputs that do not delimit packet boundaries.

Parameters

dst	The destination object.
mode	Select packet mode or stream mode.

Returns: True if the output was finalized successfully.

Definition at line 234 of file io_readable.cc.

◆ copy_to()

unsigned Readable::copy_to ( satcat5::io::Writeable * dst )

inherited

Copy data to a Writeable object, without finalizing.

Copy the contents of this Readable to a Writeable object, stopping at end-of-input, end-of-frame, or the capacity of the destination buffer (whichever comes first). This method does not call read_finalize or write_finalize(). To automatically make finalize calls,

See also: copy_and_finalize.

Returns: The number of bytes copied.

Definition at line 214 of file io_readable.cc.

◆ data_unlink()

virtual void satcat5::io::EventListener::data_unlink ( satcat5::io::Readable * src )

inlinevirtualinherited

Unlink this EventListener from the designated source, because the designated Readable object is being destroyed.

Child objects of io::EventListener MAY override this method if action is required.

Reimplemented in satcat5::io::Override, satcat5::io::MuxUp, satcat5::io::MuxDown, satcat5::io::BufferedPackets, satcat5::io::BufferedStream, satcat5::io::BufferedCopy, satcat5::eth::SwitchLogReader, satcat5::eth::Dispatch, satcat5::ccsds_spp::Dispatch, satcat5::ccsds_aos::Dispatch, satcat5::ccsds_aos::Channel, satcat5::test::MockOffload::Port, and satcat5::freertos::MessageCopy.

Definition at line 54 of file io_readable.h.

◆ get_read_ready()

unsigned ReadableRedirect::get_read_ready ( ) const

overridevirtualinherited

How many bytes can be read without blocking?

Child objects of io::Readable MUST override this method.

Implements satcat5::io::Readable.

Definition at line 336 of file io_readable.cc.

◆ get_write_space()

unsigned WriteableRedirect::get_write_space ( ) const

overridevirtualinherited

How many bytes can be written without blocking?

Child objects of io::Writeable MUST override this method.

Implements satcat5::io::Writeable.

Definition at line 236 of file io_writeable.cc.

◆ read_bytes()

bool ReadableRedirect::read_bytes	(	unsigned	nbytes,
		void *	dst
	)

overridevirtualinherited

Read 0 or more bytes into a buffer.

Child objects of io::Readable MAY override this method for improved performance.

Reimplemented from satcat5::io::Readable.

Definition at line 339 of file io_readable.cc.

◆ read_consume()

bool ReadableRedirect::read_consume ( unsigned nbytes )

overridevirtualinherited

Read and discard 0 or more bytes.

Child objects of io::Readable MAY override this method for improved performance.

Reimplemented from satcat5::io::Readable.

Definition at line 342 of file io_readable.cc.

◆ read_finalize()

void ReadableRedirect::read_finalize ( )

overridevirtualinherited

Consume any remaining bytes in this frame, if applicable.

Child objects of io::Readable SHOULD override this method if they support framing.

Reimplemented from satcat5::io::Readable.

Definition at line 345 of file io_readable.cc.

◆ read_next()

u8 ReadableRedirect::read_next ( )

overrideprotectedvirtualinherited

Read the next byte from the underlying buffer or device.

Child objects of io::Readable MUST override this method.

Implements satcat5::io::Readable.

Definition at line 348 of file io_readable.cc.

◆ read_notify()

void Readable::read_notify ( )

protectedinherited

Attempt notification by calling m_callback->data_rcvd().

Child objects of io::Readable MAY call this to override default notifications.

Definition at line 254 of file io_readable.cc.

◆ read_str()

unsigned Readable::read_str	(	unsigned	dst_size,
		char *	dst
	)

inherited

Safely read a null-terminated input string.

The input is always consumed up to the end-of-input or the first zero byte, whichever comes first.

Returns: The length of the output string, which may be truncated as needed to fit in the provided buffer.

Definition at line 179 of file io_readable.cc.

◆ read_u8()

u8 Readable::read_u8 ( )

inherited

One of many functions for reading integer/floating point values, see details.

Several functions are provided for reading and writing scalar types to/from io::Readable and io::Writeable instances. Since there are many of these that are frequently inherited, they are hidden from documentation. These functions follow a shared template:

read_ or write_ prefix.
u for unsigned, s for signed, f for floating-point.
Data-type width in bits.
- Available widths for ints: 8/16/24/32/48/64.
- Available widths for floats: 32/64.
l suffix if little-endian, no suffix if big-endian.

Example: write_s48l is "Write 48 bits (6 bytes) to this io::Writeable as a signed value in little-endian order".

Definition at line 44 of file io_readable.cc.

◆ read_underflow()

void ReadableRedirect::read_underflow ( )

overrideprotectedvirtualinherited

Optional error handling for read underflow.

Child objects of io::Readable MAY override this method.

Reimplemented from satcat5::io::Readable.

Definition at line 351 of file io_readable.cc.

◆ request_poll()

void satcat5::poll::OnDemand::request_poll ( )

inherited

Call this method to request polling at a later time.

Safe to stack requests, but only one call to poll().

Definition at line 208 of file polling.cc.

◆ set_callback()

void ReadableRedirect::set_callback ( satcat5::io::EventListener * callback )

overridevirtualinherited

Update registered callback for data_rcvd() events.

Child objects of io::Readable SHOULD usually leave this method as-is.

Reimplemented from satcat5::io::Readable.

Definition at line 331 of file io_readable.cc.

◆ write_abort()

void WriteableRedirect::write_abort ( )

overridevirtualinherited

If possible, abort the current partially-written packet.

Child objects of io::Writeable SHOULD override this method if it is practical to prevent in-progress data from being relayed downstream.

Reimplemented from satcat5::io::Writeable.

Definition at line 239 of file io_writeable.cc.

◆ write_bytes()

void WriteableRedirect::write_bytes	(	unsigned	nbytes,
		const void *	src
	)

overridevirtualinherited

Write 0 or more bytes from a buffer.

Child objects of io::Writeable MAY override write_bytes as needed for performance.

Reimplemented from satcat5::io::Writeable.

Definition at line 242 of file io_writeable.cc.

◆ write_finalize()

bool WriteableRedirect::write_finalize ( )

overridevirtualinherited

Mark end of frame and release temporary working data.

Child objects of io::Writeable SHOULD override this method to mark frame bounds.

Returns: True if successful, false on error.

Reimplemented from satcat5::io::Writeable.

Definition at line 245 of file io_writeable.cc.

◆ write_next()

void WriteableRedirect::write_next ( u8 data )

overrideprotectedvirtualinherited

Write the next byte to the underlying buffer or device.

Child objects of io::Writeable MUST override this method.

Implements satcat5::io::Writeable.

Definition at line 248 of file io_writeable.cc.

◆ write_overflow()

void WriteableRedirect::write_overflow ( )

overrideprotectedvirtualinherited

Optional error handling for write overflow.

Child objects of io::Writeable MAY override this method for error handling.

Reimplemented from satcat5::io::Writeable.

Definition at line 251 of file io_writeable.cc.

◆ write_str()

void Writeable::write_str ( const char * str )

inherited

Write the contents of a null-terminated string.

Note: Null-termination is not copied to the output.

Definition at line 180 of file io_writeable.cc.

◆ write_u8()

void Writeable::write_u8 ( u8 data )

inherited

One of many functions for writing integer/floating point values, see details.

Several functions are provided for reading and writing scalar types to/from io::Readable and io::Writeable instances. Since there are many of these that are frequently inherited, they are hidden from documentation. These functions follow a shared template:

read_ or write_ prefix.
u for unsigned, s for signed, f for floating-point.
Data-type width in bits.
- Available widths for ints: 8/16/24/32/48/64.
- Available widths for floats: 32/64.
l suffix if little-endian, no suffix if big-endian.

Example: write_s48l is "Write 48 bits (6 bytes) to this io::Writeable as a signed value in little-endian order".

Definition at line 20 of file io_writeable.cc.

Member Data Documentation

◆ m_callback

satcat5::io::EventListener* satcat5::io::Readable::m_callback

privateinherited

Pointer to the callback object, or NULL.

This can only be modified through the set_callback(...) method.

Definition at line 199 of file io_readable.h.

The documentation for this class was generated from the following file:

sam_usart.h

Detailed Description

template<unsigned SIZE = SATCAT5_SAMV71_UART_BUFFSIZE> class satcat5::sam::UsartSamv71Static< SIZE >

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ UsartSamv71Static()

Member Function Documentation

◆ configure()

◆ copy_and_finalize()

◆ copy_to()

◆ data_unlink()

◆ get_read_ready()

◆ get_write_space()

◆ read_bytes()

◆ read_consume()

◆ read_finalize()

◆ read_next()

◆ read_notify()

◆ read_str()

◆ read_u8()

◆ read_underflow()

◆ request_poll()

◆ set_callback()

◆ write_abort()

◆ write_bytes()

◆ write_finalize()

◆ write_next()

◆ write_overflow()

◆ write_str()

◆ write_u8()

Member Data Documentation

◆ m_callback

template<unsigned SIZE = SATCAT5_SAMV71_UART_BUFFSIZE>
class satcat5::sam::UsartSamv71Static< SIZE >