Detailed Description

template<unsigned SIZE = SATCAT5_DEFAULT_PKTBUFF>
class satcat5::io::PacketBufferStatic< SIZE >

Packet buffer with statically-allocated working memory.

This PacketBuffer wrapper retains packet boundaries using write_finalize(). Calling read_finalize() will discard any remaining bytes in the current packet, then advance to the next packet for subsequent reads. The maximum number of queued packets is set by the constructor, defaulting to 32.

The working buffer is statically allocated. For a heap-allocated equivalent,

See also: PacketBufferHeap (if your system has a heap).

Optional template parameter specifies buffer size. If user does not specify a size, use SATCAT5_DEFAULT_PKTBUFF = 1600 bytes.

Definition at line 198 of file pkt_buffer.h.

#include <pkt_buffer.h>

Inheritance diagram for satcat5::io::PacketBufferStatic< SIZE >:

[legend]

Collaboration diagram for satcat5::io::PacketBufferStatic< SIZE >:

[legend]

Public Member Functions
	PacketBufferStatic (unsigned max_pkt=32)
	Link the parent object to the statically allocated buffer. More...

void	clear ()
	Reset buffer contents. More...

unsigned	byte_count (bool reset=true) override
	Bytes transferred since the last query.

unsigned	frame_count (bool reset=true) override
	Frames transferred since the last query.

u8	get_percent_full () const
	Get overall buffer occupancy as percentage full (0-100%).

unsigned	get_write_partial () const
	Get number of bytes in a partial packet, or -1 on overflow.

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

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

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

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

void	zcw_write (unsigned nbytes)
	Zero-copy write (zcw) mode, required for UART interface. More...

unsigned	zcw_maxlen () const
	Max contiguous write length (ZCW).

u8 *	zcw_start ()
	Pointer to a contiguous buffer (ZCW).

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

const u8 *	peek (unsigned nbytes) const
	Peek `nbytes` into the circular buffer. More...

unsigned	get_peek_ready () const
	Find the longest available contiguous segment that can be requested by peek().

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;`

virtual void	set_callback (satcat5::io::EventListener *callback)
	Update registered callback for data_rcvd() events. 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().

virtual unsigned	error_count (bool reset=true)
	(Optional) Error events since the last query.


u8 *	get_buff_dtor () const
	Accessor for children that need to delete underlying buffer. More...

unsigned	get_buff_size () const
	Accessor for children that need to delete underlying buffer. More...

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

Protected Member Functions
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...

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

bool	can_read_internal (unsigned nbytes) const

void	consume_internal (unsigned nbytes)

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

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

Protected Attributes
friend	LimitedWrite

friend	WriteableBroadcast

friend	WriteableRedirect

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

Private Attributes
u8	m_raw [SIZE]

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

satcat5::poll::OnDemand *	m_next

bool	m_idle


u8 *const	m_buff
	State for the main circular buffer (read domain)

const unsigned	m_buff_size
	State for the main circular buffer (read domain)

unsigned	m_buff_rdidx
	State for the main circular buffer (read domain)

unsigned	m_buff_rdcount
	State for the main circular buffer (read domain)


u16 *const	m_pkt_lbuff
	Store packet lengths in an auxiliary buffer (read domain)

const unsigned	m_pkt_maxct
	Store packet lengths in an auxiliary buffer (read domain)

unsigned	m_pkt_rdidx
	Store packet lengths in an auxiliary buffer (read domain)


unsigned	m_total_bytes
	Cumulative total-bytes and total-frames statistics counters.

unsigned	m_total_frames
	Cumulative total-bytes and total-frames statistics counters.


unsigned	m_next_wrpos
	Working state for writes (write domain)

unsigned	m_next_wrlen
	Working state for writes (write domain)


volatile unsigned	m_shared_rdavail
	Shared state is constant except for cross-domain events.

volatile unsigned	m_shared_pktcount
	Shared state is constant except for cross-domain events.

Constructor & Destructor Documentation

◆ PacketBufferStatic()

template<unsigned SIZE = SATCAT5_DEFAULT_PKTBUFF>

satcat5::io::PacketBufferStatic< SIZE >::PacketBufferStatic ( unsigned max_pkt = 32 )

inlineexplicit

Link the parent object to the statically allocated buffer.

Note: PacketBufferStatic(0) is the same as StreamBufferStatic.

Definition at line 202 of file pkt_buffer.h.

Member Function Documentation

◆ clear()

void PacketBuffer::clear ( )

inherited

Reset buffer contents.

Note: This does not reset byte_count and frame_count.

Definition at line 22 of file pkt_buffer.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.

◆ get_buff_dtor()

u8* satcat5::io::PacketBuffer::get_buff_dtor ( ) const

inlineinherited

Accessor for children that need to delete underlying buffer.

Returned value matches pointer passed to the constructor.

Definition at line 137 of file pkt_buffer.h.

◆ get_buff_size()

unsigned satcat5::io::PacketBuffer::get_buff_size ( ) const

inlineinherited

Accessor for children that need to delete underlying buffer.

Returned value matches pointer passed to the constructor.

Definition at line 138 of file pkt_buffer.h.

◆ get_read_ready()

unsigned PacketBuffer::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 177 of file pkt_buffer.cc.

◆ get_write_space()

unsigned PacketBuffer::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 52 of file pkt_buffer.cc.

◆ peek()

const u8 * PacketBuffer::peek ( unsigned nbytes ) const

inherited

Peek nbytes into the circular buffer.

Due to this circular buffer, packet data may not be contiguous. Use get_peek_ready() to find the longest available contiguous segment.

Returns: A pointer to packet data, or NULL if nbytes > get_peek_ready().

Definition at line 248 of file pkt_buffer.cc.

◆ read_bytes()

bool PacketBuffer::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 187 of file pkt_buffer.cc.

◆ read_consume()

bool PacketBuffer::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 256 of file pkt_buffer.cc.

◆ read_finalize()

void PacketBuffer::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 266 of file pkt_buffer.cc.

◆ read_next()

u8 PacketBuffer::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 206 of file pkt_buffer.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 Readable::read_underflow ( )

protectedvirtualinherited

Optional error handling for read underflow.

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

Reimplemented in satcat5::port::Mailmap, and satcat5::io::ReadableRedirect.

Definition at line 271 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 Readable::set_callback ( satcat5::io::EventListener * callback )

virtualinherited

Update registered callback for data_rcvd() events.

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

Reimplemented in satcat5::io::ReadableRedirect, satcat5::io::Override, satcat5::io::MuxPort, and satcat5::test::EthernetInterface.

Definition at line 39 of file io_readable.cc.

◆ write_abort()

void PacketBuffer::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 89 of file pkt_buffer.cc.

◆ write_bytes()

void PacketBuffer::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 73 of file pkt_buffer.cc.

◆ write_finalize()

bool PacketBuffer::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 105 of file pkt_buffer.cc.

◆ write_next()

void PacketBuffer::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 93 of file pkt_buffer.cc.

◆ write_overflow()

void PacketBuffer::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 101 of file pkt_buffer.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.

◆ zcw_write()

void PacketBuffer::zcw_write ( unsigned nbytes )

inherited

Zero-copy write (zcw) mode, required for UART interface.

Create an AtomicLock object to ensure thread safety (MANDATORY).
Call zcw_maxlen() to find maximum contiguous write length.
Call zcw_start() to get a pointer to that contiguous buffer.
Call zcw_write(N) once those bytes have been written.

Definition at line 164 of file pkt_buffer.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:

pkt_buffer.h

Detailed Description

template<unsigned SIZE = SATCAT5_DEFAULT_PKTBUFF> class satcat5::io::PacketBufferStatic< SIZE >

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Constructor & Destructor Documentation

◆ PacketBufferStatic()

Member Function Documentation

◆ clear()

◆ copy_and_finalize()

◆ copy_to()

◆ get_buff_dtor()

◆ get_buff_size()

◆ get_read_ready()

◆ get_write_space()

◆ peek()

◆ 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()

◆ zcw_write()

Member Data Documentation

◆ m_callback

template<unsigned SIZE = SATCAT5_DEFAULT_PKTBUFF>
class satcat5::io::PacketBufferStatic< SIZE >