Group baton_protocol¶

CRC-16, incremental stream parser and frame encoder. More...

Classes¶

Type	Name
struct	baton_frame One decoded frame (header fields and payload, without SYNC and CRC).
struct	baton_parser Incremental parser state for one byte stream.

Public Functions¶

Type	Name
uint16_t	baton_crc16 (const uint8_t * data, size_t length) Calculate the CRC-16/CCITT-FALSE of a buffer (poly 0x1021, init 0xFFFF).
uint16_t	baton_crc16_update (uint16_t crc, uint8_t byte) Add one byte to a CRC-16/CCITT-FALSE register.
int	baton_encode (uint8_t dst, uint8_t src, uint8_t ctrl, const uint8_t * payload, size_t payload_length, uint8_t * output, size_t output_capacity, size_t * output_length) Encode one frame: SYNC, header, payload and CRC.
int	baton_parser_feed (struct baton_parser * parser, uint8_t byte) Feed one byte to the incremental frame parser.
void	baton_parser_init (struct baton_parser * parser) Reset a parser before starting or restarting a byte stream.

Macros¶

Type	Name
define	BATON_CRC_INIT `0xFFFFU` Initial value of the CRC-16/CCITT-FALSE register.
define	BATON_FRAME_MAX `([BATON\_FRAME\_OVERHEAD](group__baton__defs.md#define-baton_frame_overhead) + [BATON\_MAX\_PAYLOAD](group__baton__config.md#define-baton_max_payload))` Largest complete frame on the wire, SYNC to CRC.
define	BATON_PARSER_IDLE `0U` Value of baton_parser::state while the parser waits for SYNC (between frames).
define	BATON_PARSE_ERROR `(-1)` Error returned for invalid input, malformed frames, or insufficient capacity.

Detailed Description¶

Pure functions over caller-owned buffers: no state outside the structures passed in, safe to use from several contexts on different structures.

** **

CRC: baton_crc16, baton_crc16_update.
Parser: baton_parser_init, baton_parser_feed.
Encoder: baton_encode.

Public Functions Documentation¶

function baton_crc16¶

Calculate the CRC-16/CCITT-FALSE of a buffer (poly 0x1021, init 0xFFFF).

uint16_t baton_crc16 (
    const uint8_t * data,
    size_t length
)

Parameters:

data Bytes covered by the CRC.
length Number of bytes to process.

Returns:

Calculated CRC; BATON_CRC_INIT when data is NULL.

function baton_crc16_update¶

Add one byte to a CRC-16/CCITT-FALSE register.

uint16_t baton_crc16_update (
    uint16_t crc,
    uint8_t byte
)

Parameters:

crc Current register value (BATON_CRC_INIT before the first byte).
byte Next byte.

Returns:

Updated register value.

function baton_encode¶

Encode one frame: SYNC, header, payload and CRC.

int baton_encode (
    uint8_t dst,
    uint8_t src,
    uint8_t ctrl,
    const uint8_t * payload,
    size_t payload_length,
    uint8_t * output,
    size_t output_capacity,
    size_t * output_length
)

payload may point to &output[BATON_HEADER_SIZE]: a payload that was built in place is then not copied.

Parameters:

dst Destination address.
src Source address.
ctrl Control byte, see baton_ctrl().
payload Payload bytes, or NULL when payload_length is zero.
payload_length Number of payload bytes (at most BATON_MAX_PAYLOAD).
output Destination buffer for the complete frame.
output_capacity Capacity of output in bytes.
output_length Receives the frame length on success.

Return value:

0 Frame encoded.
BATON_PARSE_ERROR Invalid input or insufficient output capacity.

function baton_parser_feed¶

Feed one byte to the incremental frame parser.

int baton_parser_feed (
    struct baton_parser * parser,
    uint8_t byte
)

The parser waits for SYNC, reads the header, rejects a LEN above BATON_MAX_PAYLOAD as soon as it is read, then reads the payload and the CRC and validates it. After a valid or invalid frame it waits for the next SYNC. Bytes of a rejected frame are not re-scanned for SYNC; the inter-byte timeout of the link resynchronizes a broken stream.

Parameters:

parser Parser state.
byte Next byte from the input stream.

Return value:

1 A complete valid frame is available in parser->frame until the next call.
0 More bytes are required.
BATON_PARSE_ERROR NULL parser, LEN out of range, CRC mismatch or corrupted state.

function baton_parser_init¶

Reset a parser before starting or restarting a byte stream.

void baton_parser_init (
    struct baton_parser * parser
)

Parameters:

parser Parser state to initialize; NULL is ignored.

Macro Definition Documentation¶

define BATON_CRC_INIT¶

Initial value of the CRC-16/CCITT-FALSE register.

#define BATON_CRC_INIT `0xFFFFU`

define BATON_FRAME_MAX¶

Largest complete frame on the wire, SYNC to CRC.

#define BATON_FRAME_MAX `( BATON_FRAME_OVERHEAD + BATON_MAX_PAYLOAD )`

define BATON_PARSER_IDLE¶

Value of baton_parser::state while the parser waits for SYNC (between frames).

#define BATON_PARSER_IDLE `0U`

define BATON_PARSE_ERROR¶

Error returned for invalid input, malformed frames, or insufficient capacity.

#define BATON_PARSE_ERROR `(-1)`