SatCat5
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
satcat5::io::ChecksumTx< T, N > Class Template Referenceabstract

Detailed Description

template<class T, unsigned N>
class satcat5::io::ChecksumTx< T, N >

Inline checksum insertion, appends FCS to each outgoing frame.

Inline checksum insertion (ChecksumTx) and verification (ChecksumRx). Many frame formats consist of frame data followed by a checksum. io::ChecksumTx and io::ChecksumRx define two templates for working with such streams. The templates are able to work with any byte-aligned checksum with byte-aligned inputs, including most CRC types and many other formats.

Each template accepts data using the io::Writeable interface and writes modified data to a designated io::Writeable pointer:

  • ChecksumTx: For each incoming frame, append the calculated checksum.
  • ChecksumRx: For each incoming frame, strip the last N bytes and compare against the calculated checksum. If it is a match call write_finalize(), and otherwise call write_abort().

Because checksum validation is often tied to a network interface, these classes include the io::Counter API for counting sent and received frames.

In all child classes of either template, the user MUST override the methods write_next() and write_finalize() to calculate and format the checksum. For child classes of io::ChecksumTx, the implementation of write_finalize() MUST call chk_finalize(). For example usage, refer to eth::ChecksumTx and eth::ChecksumRx.

Template type T stores the checksum (u8/u16/u32/u64). Template value N is the checksum length in bytes.

Child class is responsible for the following:

  • Implement the chk_reset() method.
  • Implement the write_next() method. This method must update the checksum calculation and increment m_frm_len.
  • Implement the write_finalize() method. This method must write the calculated checksum, then call chk_finalize(), then proceed only if the returned value is true.

Definition at line 83 of file io_checksum.h.

#include <io_checksum.h>

Inheritance diagram for satcat5::io::ChecksumTx< T, N >:
[legend]
Collaboration diagram for satcat5::io::ChecksumTx< T, N >:
[legend]

Public Member Functions

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...
 
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.
 
unsigned error_count (bool reset=true) override
 (Optional) Error events since the last query.
 
void byte_incr (unsigned incr)
 Increment any of the internal counters.
 
void frame_incr (unsigned incr)
 
void error_incr (unsigned incr)
 
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...
 
virtual bool write_finalize ()
 Mark end of frame and release temporary working data. 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;
 

Protected Member Functions

 ChecksumTx (satcat5::io::Writeable *dst, T init)
 Only the child class has access to the constructor.
 
void chk_reset () override
 Reset checksum calculation to its initial state.
 
bool chk_finalize ()
 Reset internal state and return true if the frame is valid. More...
 
void write_overflow () override
 Optional error handling for write overflow. More...
 
virtual void write_next (u8 data)=0
 Write the next byte to the underlying buffer or device. More...
 

Protected Attributes

T m_chk
 Checksum state.
 
const T m_init
 State after reset.
 
satcat5::io::Writeable *const m_dst
 Output object.
 
bool m_ovr
 Overflow flag.
 
unsigned m_byte_ct
 Cumulative byte count.
 
unsigned m_err_ct
 Cumulative error count.
 
unsigned m_frm_ct
 Cumulative frame count.
 
unsigned m_frm_len
 Length of current frame.
 
friend LimitedWrite
 
friend WriteableBroadcast
 
friend WriteableRedirect
 

Member Function Documentation

◆ chk_finalize()

bool ChecksumTxCommon::chk_finalize ( )
protectedinherited

Reset internal state and return true if the frame is valid.

i.e., If false, do not forward the write_finalize() event.

Definition at line 24 of file io_checksum.cc.

◆ get_write_space()

template<class T , unsigned N>
unsigned satcat5::io::ChecksumTx< T, N >::get_write_space ( ) const
inlineoverridevirtual

How many bytes can be written without blocking?

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

Implements satcat5::io::Writeable.

Definition at line 86 of file io_checksum.h.

◆ write_abort()

void ChecksumTxCommon::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 16 of file io_checksum.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 Writeable::write_finalize ( )
virtualinherited

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 in satcat5::port::Mailmap, satcat5::io::PacketBuffer, satcat5::io::MultiWriterBypass, satcat5::io::MultiWriter, satcat5::io::WriteableRedirect, satcat5::io::ArrayWrite, satcat5::io::WriteableThrottle, satcat5::io::CounterInline, satcat5::io::WriteableBroadcastAny, satcat5::io::WriteableBroadcast, satcat5::eth::SwitchPort, satcat5::eth::ChecksumRx, satcat5::eth::ChecksumTx, satcat5::crc16::XmodemRx, satcat5::crc16::XmodemTx, satcat5::crc16::KermitRx, satcat5::crc16::KermitTx, satcat5::io::SlipEncoder, satcat5::io::HdlcEncoder::ByteStuff, satcat5::io::CobsEncoder, satcat5::coap::Connection, satcat5::test::EthernetInterface, satcat5::io::BufferedTee, satcat5::io::WritePcapInterface, satcat5::io::WritePcap, satcat5::io::FileWriter, and satcat5::util::ChatPrinter.

Definition at line 185 of file io_writeable.cc.

◆ write_next()

virtual void satcat5::io::Writeable::write_next ( u8  data)
protectedpure virtualinherited

Write the next byte to the underlying buffer or device.

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

Implemented 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::ArrayWrite, satcat5::io::CounterInline, satcat5::io::WriteableBroadcast, satcat5::eth::ChecksumRx, satcat5::eth::ChecksumTx, satcat5::crc16::XmodemRx, satcat5::crc16::XmodemTx, satcat5::crc16::KermitRx, satcat5::crc16::KermitTx, satcat5::io::SlipDecoder, satcat5::io::SlipEncoder, satcat5::io::HdlcDecoder, satcat5::io::HdlcEncoder::ByteStuff, satcat5::io::CobsDecoder, satcat5::io::CobsEncoder, satcat5::ccsds_spp::Packetizer, satcat5::io::FileWriter, and satcat5::util::ChatPrinter.

◆ write_overflow()

void ChecksumTxCommon::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 12 of file io_checksum.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.

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