Detailed Description

Simulation of a PTP-compatible Ethernet interface controller.

This class simulates a PTP-compatible endpoint in a back-to-back Ethernet network of two nodes.

See also: test::Crosslink

Definition at line 20 of file eth_interface.h.

#include <eth_interface.h>

Inheritance diagram for satcat5::test::EthernetInterface:

[legend]

Collaboration diagram for satcat5::test::EthernetInterface:

[legend]

Public Member Functions
	EthernetInterface (satcat5::io::Writeable *pcap)
	Create a simulated interface, with optional packet-capture.

void	connect (satcat5::test::EthernetInterface *dst)
	Crosslink to specified destination object.

void	support_one_step (bool en)
	Enable or disable support for one-step timestamps.

satcat5::ptp::Time	ptp_time_now () override
	Return the best available estimate of the current time. More...

satcat5::ptp::Time	ptp_tx_start () override
	Begin sending a timestamped message. More...

satcat5::ptp::Time	ptp_tx_timestamp () override
	Return timestamp of the most recent outgoing message. More...

satcat5::ptp::Time	ptp_rx_timestamp () override
	Return timestamp of the current incoming message. More...

satcat5::io::Writeable *	ptp_tx_write () override
	Return an object suitable for writing the next PTP frame. More...

satcat5::io::Readable *	ptp_rx_read () override
	Return an object suitable for reading the next PTP frame. More...

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

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

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

void	set_loss_rate (float rate)
	Set rate for randomized drops of outgoing packets.

void	set_zero_pad (unsigned len)
	Set minimum frame length. Runt frames are zero-padded.

unsigned	tx_count () const
	Count packets sent.

unsigned	rx_count () const
	Count packets received.

void	ptp_callback (satcat5::poll::OnDemand *obj)
	Set callback object for PTP-related packet handling.

satcat5::ptp::PacketType	ptp_rx_type () const
	Return the packet type for the most recent message.

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_overflow () override
	Optional error handling for write overflow. More...

const u8 *	buffer () const
	Read-only access to the working buffer.

unsigned	written_len () const
	Report total length after write_finalize() is called.

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

virtual void	write_bytes (unsigned nbytes, const void *src)
	Write 0 or more bytes from a buffer. 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	data_unlink (satcat5::io::Readable *src)
	Unlink this EventListener from the designated source, because the designated Readable object is being destroyed. 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...

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

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

Protected Member Functions
void	data_rcvd (satcat5::io::Readable *src) override
	The data_rcvd() callback is polled whenever data is available. More...

void	read_begin_packet ()

bool	ptp_dispatch (const u8 *peek, unsigned length)
	Determine if an incoming packet is a PTP message. More...

void	ptp_notify_now ()
	Notify the PTP callback object in immediate mode.

void	ptp_notify_req ()
	Notify the PTP callback object in deferred mode.

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

Protected Attributes
satcat5::io::Writeable *	m_txpcap

satcat5::io::Writeable *	m_txbuff_data

satcat5::io::Writeable *	m_txbuff_time

satcat5::io::PacketBufferHeap	m_rxbuff_data

satcat5::io::PacketBufferHeap	m_rxbuff_time

satcat5::ptp::Time	m_time_rx

satcat5::ptp::Time	m_time_tx0

satcat5::ptp::Time	m_time_tx1

unsigned	m_tx_count

unsigned	m_rx_count

unsigned	m_zero_pad

bool	m_support_one_step

u32	m_loss_threshold

u8	m_txbuff [1600]

friend	LimitedWrite

friend	WriteableBroadcast

friend	WriteableRedirect

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

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

Private Attributes
satcat5::poll::OnDemand *	m_ptp_callback

satcat5::ptp::PacketType	m_ptp_rx_type

u8 *const	m_dst

const unsigned	m_len

bool	m_ovr

unsigned	m_wridx

unsigned	m_wrlen

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

Member Function Documentation

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

void EthernetInterface::data_rcvd ( satcat5::io::Readable * src )

overrideprotectedvirtual

The data_rcvd() callback is polled whenever data is available.

A pointer is provided to assist handlers with multiple sources. Child objects of io::EventListener MUST override this method.

Implements satcat5::io::EventListener.

Definition at line 155 of file eth_interface.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 ArrayWrite::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 189 of file io_writeable.cc.

◆ ptp_dispatch()

bool Interface::ptp_dispatch	(	const u8 *	peek,
		unsigned	length
	)

protectedinherited

Determine if an incoming packet is a PTP message.

Child class MUST call this method for each received packet. If this method returns true, call ptp_notify_now() or ptp_notify_req(). Otherwise, continue normal processing.

Definition at line 18 of file ptp_interface.cc.

◆ ptp_rx_read()

Readable * EthernetInterface::ptp_rx_read ( )

overridevirtual

Return an object suitable for reading the next PTP frame.

(This may be the primary interface or a separate pointer.) Child class MUST override this method.

Implements satcat5::ptp::Interface.

Definition at line 217 of file eth_interface.cc.

◆ ptp_rx_timestamp()

Time EthernetInterface::ptp_rx_timestamp ( )

overridevirtual

Return timestamp of the current incoming message.

Child class MUST override this method.

Implements satcat5::ptp::Interface.

Definition at line 213 of file eth_interface.cc.

◆ ptp_time_now()

Time EthernetInterface::ptp_time_now ( )

overridevirtual

Return the best available estimate of the current time.

(This method may be less accurate than Tx and Rx timestamps.)

Implements satcat5::ptp::Interface.

Definition at line 196 of file eth_interface.cc.

◆ ptp_tx_start()

Time EthernetInterface::ptp_tx_start ( )

overridevirtual

Begin sending a timestamped message.

Return effective one-step timestamp if known, otherwise zero. Child class MUST override this method.

Implements satcat5::ptp::Interface.

Definition at line 54 of file eth_interface.cc.

◆ ptp_tx_timestamp()

Time EthernetInterface::ptp_tx_timestamp ( )

overridevirtual

Return timestamp of the most recent outgoing message.

Child class MUST override this method.

Implements satcat5::ptp::Interface.

Definition at line 211 of file eth_interface.cc.

◆ ptp_tx_write()

Writeable * EthernetInterface::ptp_tx_write ( )

overridevirtual

Return an object suitable for writing the next PTP frame.

(This may be the primary interface or a separate pointer.) Child class MUST override this method.

Implements satcat5::ptp::Interface.

Definition at line 215 of file eth_interface.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 EthernetInterface::read_finalize ( )

overridevirtual

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 72 of file eth_interface.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 EthernetInterface::set_callback ( satcat5::io::EventListener * callback )

overridevirtual

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 62 of file eth_interface.cc.

◆ write_abort()

void ArrayWrite::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 193 of file io_writeable.cc.

◆ write_bytes()

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

virtualinherited

Write 0 or more bytes from a buffer.

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

Reimplemented in satcat5::port::MailmapAligned, satcat5::port::Mailmap, satcat5::io::PacketBuffer, satcat5::io::MultiWriter, satcat5::io::MultiPacket::Overwriter, satcat5::io::NullWrite, satcat5::io::WriteableRedirect, satcat5::io::LimitedWrite, satcat5::io::CounterInline, satcat5::io::WriteableBroadcast, and satcat5::io::FileWriter.

Definition at line 170 of file io_writeable.cc.

◆ write_finalize()

bool EthernetInterface::write_finalize ( )

overridevirtual

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 85 of file eth_interface.cc.

◆ write_next()

void ArrayWrite::write_next ( u8 data )

overrideprivatevirtualinherited

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 211 of file io_writeable.cc.

◆ write_overflow()

void ArrayWrite::write_overflow ( )

overridevirtualinherited

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 207 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 files:

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Member Function Documentation

◆ copy_and_finalize()

◆ copy_to()

◆ data_rcvd()

◆ data_unlink()

◆ get_read_ready()

◆ get_write_space()

◆ ptp_dispatch()

◆ ptp_rx_read()

◆ ptp_rx_timestamp()

◆ ptp_time_now()

◆ ptp_tx_start()

◆ ptp_tx_timestamp()

◆ ptp_tx_write()

◆ 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