pw_hdlc

Overview

Simple, robust, and efficient serial communication.

Main docs: Home

Classes
class	pw::hdlc::Frame
class	pw::hdlc::Decoder
class	pw::hdlc::DecoderBuffer< kSizeBytes >
	Declares a buffer along with a Decoder. More...
class	pw::hdlc::Encoder
	Encodes and writes HDLC frames. More...
class	pw::hdlc::Router

Functions
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)
	Constructs 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
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

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

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.

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

• 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 a 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

• 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

send_address

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

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