Oveview

Simple, robust, and efficient serial communication. Main docs: https://pigweed.dev/pw_hdlc.

Classes
class	pw::hdlc::Frame

class	pw::hdlc::Decoder

class	pw::hdlc::DecoderBuffer< kSizeBytes >

class	pw::hdlc::Encoder
	Encodes and writes HDLC frames. More...

class	pw::hdlc::Router

Functions
static Result< Frame >	pw::hdlc::Frame::Parse (ConstByteSpan frame)

constexpr uint64_t	pw::hdlc::Frame::address () const

constexpr std::byte	pw::hdlc::Frame::control () const

constexpr ConstByteSpan	pw::hdlc::Frame::data () const

constexpr	pw::hdlc::Decoder::Decoder (ByteSpan buffer)

	pw::hdlc::Decoder::Decoder (const Decoder &)=delete

Decoder &	pw::hdlc::Decoder::operator= (const Decoder &)=delete

	pw::hdlc::Decoder::Decoder (Decoder &&)=default

Decoder &	pw::hdlc::Decoder::operator= (Decoder &&)=default

Result< Frame >	pw::hdlc::Decoder::Process (std::byte new_byte)
	Parses a single byte of an HDLC stream.

static constexpr size_t	pw::hdlc::Decoder::RequiredBufferSizeForFrameSize (size_t max_frame_size)

template<typename F , typename... Args>
void	pw::hdlc::Decoder::Process (ConstByteSpan data, F &&callback, Args &&... args)
	Processes a span of data and calls the provided callback with each frame or error.

size_t	pw::hdlc::Decoder::max_size () const

void	pw::hdlc::Decoder::Clear ()

	pw::hdlc::DecoderBuffer< kSizeBytes >::DecoderBuffer (DecoderBuffer &&)=delete

DecoderBuffer &	pw::hdlc::DecoderBuffer< kSizeBytes >::operator= (DecoderBuffer &&)=delete

static constexpr size_t	pw::hdlc::DecoderBuffer< kSizeBytes >::max_size ()

Status	pw::hdlc::WriteUIFrame (uint64_t address, ConstByteSpan payload, stream::Writer &writer)
	Writes an HDLC unnumbered information frame (UI frame) to the provided `pw::stream` writer.

constexpr	pw::hdlc::Encoder::Encoder (stream::Writer &output)
	Construct an encoder which will write data to `output`.

Status	pw::hdlc::Encoder::StartUnnumberedFrame (uint64_t address)

Status	pw::hdlc::Encoder::WriteData (ConstByteSpan data)

Status	pw::hdlc::Encoder::FinishFrame ()
	Finishes a frame. Writes the frame check sequence and a terminating flag.

	pw::hdlc::Router::Router (pw::channel::ByteReaderWriter &io_channel, ByteSpan decode_buffer)

	pw::hdlc::Router::Router (const Router &)=delete

Router &	pw::hdlc::Router::operator= (const Router &)=delete

	pw::hdlc::Router::Router (Router &&)=delete

Router &	pw::hdlc::Router::operator= (Router &&)=delete

Status	pw::hdlc::Router::AddChannel (pw::channel::DatagramReaderWriter &channel, uint64_t receive_address, uint64_t send_address)

Status	pw::hdlc::Router::RemoveChannel (pw::channel::DatagramReaderWriter &channel, uint64_t receive_address, uint64_t send_address)

pw::async2::Poll	pw::hdlc::Router::Pend (pw::async2::Context &cx)

pw::async2::Poll	pw::hdlc::Router::PendClose (pw::async2::Context &cx)
	Closes all underlying channels, attempting to flush any data.

	pw::hdlc::Router::ChannelData::ChannelData (pw::channel::DatagramReaderWriter &channel_arg, uint64_t receive_address_arg, uint64_t send_address_arg)

	pw::hdlc::Router::ChannelData::ChannelData (const ChannelData &)=delete

ChannelData &	pw::hdlc::Router::ChannelData::operator= (const ChannelData &)=delete

	pw::hdlc::Router::ChannelData::ChannelData (ChannelData &&)=default

ChannelData &	pw::hdlc::Router::ChannelData::operator= (ChannelData &&)=default

Variables
static constexpr size_t	pw::hdlc::Frame::kMinContentSizeBytes

pw::channel::DatagramReaderWriter *	pw::hdlc::Router::ChannelData::channel
	A channel which reads and writes datagrams.

uint64_t	pw::hdlc::Router::ChannelData::receive_address
	Data received over HDLC with this address will be sent to `channel`.

uint64_t	pw::hdlc::Router::ChannelData::send_address

pw::multibuf::MultiBuf	pw::hdlc::Router::OutgoingBuffer::buffer

size_t	pw::hdlc::Router::OutgoingBuffer::hdlc_encoded_size

uint64_t	pw::hdlc::Router::OutgoingBuffer::target_address

Function Documentation

◆ AddChannel()

Status pw::hdlc::Router::AddChannel	(	pw::channel::DatagramReaderWriter &	channel,
		uint64_t	receive_address,
		uint64_t	send_address
	)

Registers a Channel tied to the provided addresses.

All incoming HDLC messages received on io_channel with HDLC address receive_address will be decoded and routed to the provided channel.

Data read from channel will be HDLC-encoded and sent to io_channel.

Note that a non-writeable channel will exert backpressure on the entire router, so channels should strive to consume or discard incoming data as quickly as possible in order to prevent starvation of other channels.

Parameters

[in]	receive_address	Incoming HDLC messages received on the external `io_channel` with an address matching `receive_address` will be decoded and written to `channel`.
[in]	send_address	Data read from `channel` will be written to `io_channel` with the HDLC address `send_address`.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: ``Channel`` was successfully registered.
* 
*     ALREADY_EXISTS: A registration already exists for either
*     ``channel``, ``receive_address``, or ``send_address``. Channels may
*     not be registered with multiple addresses, nor may addresses be
*     used with multiple channels.
* 
*

◆ DecoderBuffer()

template<size_t kSizeBytes>

pw::hdlc::DecoderBuffer< kSizeBytes >::DecoderBuffer ( DecoderBuffer< kSizeBytes > && )

delete

DecoderBuffer is not movable, as the decoder stores pointers into the frame buffer.

◆ operator=()

template<size_t kSizeBytes>

DecoderBuffer & pw::hdlc::DecoderBuffer< kSizeBytes >::operator= ( DecoderBuffer< kSizeBytes > && )

delete

DecoderBuffer is not movable, as the decoder stores pointers into the frame buffer.

◆ Pend()

pw::async2::Poll pw::hdlc::Router::Pend ( pw::async2::Context & cx )

Progress the router as far as possible, waking the provided cx when more progress can be made.

This will only return Ready if io_channel has been observed as closed, after which all messages have been flushed to the remaining channels and the channels have been closed.

◆ Process()

Result< Frame > pw::hdlc::Decoder::Process ( std::byte new_byte )

Parses a single byte of an HDLC stream.

Returns

embed:rst:leading-asterisk
 
*  A ``pw::Result`` with the complete frame if the byte completes a
*  frame. The status can be one of the following:
* 
*  .. pw-status-codes::
* 
*     OK: A frame was successfully decoded. The ``Result`` contains
*     the ``Frame``, which is invalidated by the next ``Process()`` call.
* 
*     UNAVAILABLE: No frame is available.
* 
*     RESOURCE_EXHAUSTED: A frame completed, but it was too large
*     to fit in the decoder's buffer.
* 
*     DATA_LOSS: A frame completed, but it was invalid. The frame
*     was incomplete or the frame check sequence verification failed.
* 
*

◆ RemoveChannel()

Status pw::hdlc::Router::RemoveChannel	(	pw::channel::DatagramReaderWriter &	channel,
		uint64_t	receive_address,
		uint64_t	send_address
	)

Removes a previously registered Channel tied to the provided addresses.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The channel was successfully deregistered.
* 
*     NOT_FOUND: A registration of the channel for the provided
*     addresses was not found.
* 
*

◆ Router()

pw::hdlc::Router::Router	(	pw::channel::ByteReaderWriter &	io_channel,
		ByteSpan	decode_buffer
	)

inline

Constructs a Router

Parameters

[in]	io_channel	The channel on which to send and receive encoded HDLC packets.
[in]	decode_buffer	The memory to use for storing partially-decoded HDLC frames. This buffer should be at least `Decoder::RequiredBufferSizeForFrameSize(frame_size)` bytes in order to ensure that HDLC frames of size `frame_size` can be successfully decoded.

◆ StartUnnumberedFrame()

Status pw::hdlc::Encoder::StartUnnumberedFrame ( uint64_t address )

inline

Writes the header for an U-frame. After successfully calling StartUnnumberedFrame, WriteData may be called any number of times.

◆ WriteData()

Status pw::hdlc::Encoder::WriteData ( ConstByteSpan data )

Writes data for an ongoing frame. Must only be called after a successful StartInformationFrame call, and prior to a FinishFrame() call.

◆ WriteUIFrame()

Status pw::hdlc::WriteUIFrame	(	uint64_t	address,
		ConstByteSpan	payload,
		stream::Writer &	writer
	)

Writes an HDLC unnumbered information frame (UI frame) to the provided pw::stream writer.

This function is a convenience alias for the more general Encoder type and set of functions.

Parameters

address	The frame address.
payload	The frame data to encode.
writer	The `pw::stream` to write the frame to. The frame contains the following bytes. See Design for more information. HDLC flag byte (`0x7e`) Address (variable length, up to 10 bytes) UI-frame control (metadata) byte Payload (0 or more bytes) Frame check sequence (CRC-32, 4 bytes) HDLC flag byte (`0x7e`)

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The write finished successfully.
* 
*     RESOURCE_EXHAUSTED: The write failed because the size of
*     the frame would be larger than the writer's conservative limit.
* 
*     INVALID_ARGUMENT: The start of the write failed. Check
*     for problems in your ``address`` argument's value.
* 
*

Variable Documentation

◆ kMinContentSizeBytes

constexpr size_t pw::hdlc::Frame::kMinContentSizeBytes

staticconstexpr

Initial value:

=

kMinAddressSize + kControlSize + kFcsSize

◆ send_address

uint64_t pw::hdlc::Router::ChannelData::send_address

Data read from channel will be sent out over HDLC with this address.

Oveview

Classes

Functions

Variables

Function Documentation

◆ AddChannel()

◆ DecoderBuffer()

◆ operator=()

◆ Pend()

◆ Process()

◆ RemoveChannel()

◆ Router()

◆ StartUnnumberedFrame()

◆ WriteData()

◆ WriteUIFrame()

Variable Documentation

◆ kMinContentSizeBytes

◆ send_address