ab_gp_channel_payload.h File Reference

Generic, data-blind wire framing for the A<->B peer link's AB_SAMPLE frame (CRC-64-protected, ADR-029) and ab_gp_channel_negotiate.c's own state-transfer extra DATA payload. This file has no knowledge of what any collector's own data represents - each module that owns wire data (today: only AB/GP/train/ab_gp_train.c, via ab_gp_train_init()) registers its own whole-array encode/decode pair with ab_gp_channel_payload_register_collector() below, claiming a fixed byte range in registration order; this file only concatenates those ranges into one buffer and CRC-64-protects the result. Pure codec/framing functions - no ab_gp_channel_context_t, no I/O, no logging beyond the fail-safe cases documented below; see ab_gp_channel_io.c for the actual rte_netlink_send()/_receive() calls that move these bytes. More...

#include <stdbool.h>
#include <stdint.h>
#include "rte/utils/status/rte_status.h"
#include "ab_gp_channel_types.h"

Include dependency graph for ab_gp_channel_payload.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS   4U

Typedefs
typedef uint32_t	ab_gp_channel_payload_collector_id_t
	Opaque handle to a registered collector - returned by ab_gp_channel_payload_register_collector() below, passed back to ab_gp_channel_payload_encode_collector()/_decode_collector() and used to index ab_gp_channel_payload_encode_ab_sample()'s/ _decode_ab_sample()'s own sources/dests arrays.
typedef void(*)	ab_gp_channel_payload_encode_fn(void *context, const void *items, uint8_t *out)
	Encodes a collector's own whole item array into its own wire_size-byte slice of a combined buffer - the collector's own function decides how many items that is and how each one is packed; this file never inspects items itself.
typedef void(*)	ab_gp_channel_payload_decode_fn(void *context, const uint8_t *in, void *out_items)
	Decodes a collector's own whole item array from its own wire_size-byte slice - see ab_gp_channel_payload_register_collector()'s own doc.

Functions
rte_status_t	ab_gp_channel_payload_register_collector (uint32_t wire_size, ab_gp_channel_payload_encode_fn encode_fn, ab_gp_channel_payload_decode_fn decode_fn, void *context, ab_gp_channel_payload_collector_id_t *out_id)
	Registers a collector: a module's own fixed-size contribution to the combined A<->B payload - a fan-out list (not a single slot), so more than one module can each contribute its own slice (e.g. train sessions today, a future route collector tomorrow) without this file changing. Each registered collector claims the next contiguous byte range in the combined buffer, in registration order. Setup-phase only (rte_lifecycle_check_setup_allowed()) - call from your own module's own _init(), itself called once from ab_gp_channel_train_codec_setup() (AB/GP/com/ab_gp_channel.c).
void	ab_gp_channel_payload_encode_collector (ab_gp_channel_payload_collector_id_t id, uint8_t *out, const void *items)
	Encodes one collector's own items into its own slice of a combined buffer - used both standalone (e.g. crosscompare's own local-vs-peer comparison buffers, negotiate's own extra DATA payload) and internally by ab_gp_channel_payload_encode_ab_sample() below.
void	ab_gp_channel_payload_decode_collector (ab_gp_channel_payload_collector_id_t id, const uint8_t *in, void *out_items)
	Decodes one collector's own items - see ab_gp_channel_payload_encode_collector() (same contract, reversed).
void	ab_gp_channel_payload_encode_ab_sample (uint8_t out[AB_SAMPLE_WIRE_SIZE], uint32_t cycle, const void *const sources[AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS])
	Encodes an A<->B peer-link sample: {cycle, every registered collector's own bytes in registration order, CRC-64 of the preceding bytes} - same "compute over everything but the CRC field itself" convention as rte_checksum_vital_message_create().
rte_status_t	ab_gp_channel_payload_decode_ab_sample (uint8_t in[AB_SAMPLE_WIRE_SIZE], uint32_t *out_cycle, void *const dests[AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS])
	Decodes and CRC-64-verifies an A<->B peer-link sample.

Detailed Description

Generic, data-blind wire framing for the A<->B peer link's AB_SAMPLE frame (CRC-64-protected, ADR-029) and ab_gp_channel_negotiate.c's own state-transfer extra DATA payload. This file has no knowledge of what any collector's own data represents - each module that owns wire data (today: only AB/GP/train/ab_gp_train.c, via ab_gp_train_init()) registers its own whole-array encode/decode pair with ab_gp_channel_payload_register_collector() below, claiming a fixed byte range in registration order; this file only concatenates those ranges into one buffer and CRC-64-protects the result. Pure codec/framing functions - no ab_gp_channel_context_t, no I/O, no logging beyond the fail-safe cases documented below; see ab_gp_channel_io.c for the actual rte_netlink_send()/_receive() calls that move these bytes.

Definition in file ab_gp_channel_payload.h.

Macro Definition Documentation

AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS

#define AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS   4U

Worst case realistically needed today: one collector (train sessions), with headroom for a couple more (e.g. a future route collector).

Definition at line 31 of file ab_gp_channel_payload.h.

Typedef Documentation

ab_gp_channel_payload_collector_id_t

typedef uint32_t ab_gp_channel_payload_collector_id_t

Opaque handle to a registered collector - returned by ab_gp_channel_payload_register_collector() below, passed back to ab_gp_channel_payload_encode_collector()/_decode_collector() and used to index ab_gp_channel_payload_encode_ab_sample()'s/ _decode_ab_sample()'s own sources/dests arrays.

Definition at line 38 of file ab_gp_channel_payload.h.

ab_gp_channel_payload_encode_fn

typedef void(*) ab_gp_channel_payload_encode_fn(void *context, const void *items, uint8_t *out)

Encodes a collector's own whole item array into its own wire_size-byte slice of a combined buffer - the collector's own function decides how many items that is and how each one is packed; this file never inspects items itself.

Parameters

context	Whatever context was passed to ab_gp_channel_payload_register_collector().
items	Source array, of whatever type/length this collector's own encode_fn expects. Must not be NULL.
out	Destination, exactly this collector's own registered wire_size bytes. Must not be NULL.

Definition at line 51 of file ab_gp_channel_payload.h.

ab_gp_channel_payload_decode_fn

typedef void(*) ab_gp_channel_payload_decode_fn(void *context, const uint8_t *in, void *out_items)

Decodes a collector's own whole item array from its own wire_size-byte slice - see ab_gp_channel_payload_register_collector()'s own doc.

Parameters

context	Whatever context was passed to ab_gp_channel_payload_register_collector().
in	Source, exactly this collector's own registered wire_size bytes. Must not be NULL.
out_items	Destination array, of whatever type/length this collector's own decode_fn expects. Must not be NULL.

Definition at line 62 of file ab_gp_channel_payload.h.

Function Documentation

ab_gp_channel_payload_register_collector()

rte_status_t ab_gp_channel_payload_register_collector	(	uint32_t	wire_size,
		ab_gp_channel_payload_encode_fn	encode_fn,
		ab_gp_channel_payload_decode_fn	decode_fn,
		void *	context,
		ab_gp_channel_payload_collector_id_t *	out_id )

Registers a collector: a module's own fixed-size contribution to the combined A<->B payload - a fan-out list (not a single slot), so more than one module can each contribute its own slice (e.g. train sessions today, a future route collector tomorrow) without this file changing. Each registered collector claims the next contiguous byte range in the combined buffer, in registration order. Setup-phase only (rte_lifecycle_check_setup_allowed()) - call from your own module's own _init(), itself called once from ab_gp_channel_train_codec_setup() (AB/GP/com/ab_gp_channel.c).

Parameters

wire_size	Total bytes this collector's own encode_fn writes (and decode_fn reads) - e.g. item count * per-item wire size, entirely this collector's own concern. Must be > 0.
encode_fn	Encoder to register. Must not be NULL.
decode_fn	Decoder to register. Must not be NULL.
context	Passed back to both callbacks verbatim on every call.
out_id	Receives this collector's own id. Must not be NULL.

Returns

RTE_STATUS_OK on success; RTE_STATUS_INVALID_PARAM for a zero wire_size or a NULL encode_fn/decode_fn/out_id; RTE_STATUS_INVALID_STATE if the setup phase is already locked; RTE_STATUS_RESOURCE_EXHAUSTED if AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS collectors are already registered.

Global variables declarations Local function declarations Global functions

Definition at line 43 of file ab_gp_channel_payload.c.

ab_gp_channel_payload_encode_collector()

void ab_gp_channel_payload_encode_collector	(	ab_gp_channel_payload_collector_id_t	id,
		uint8_t *	out,
		const void *	items )

Encodes one collector's own items into its own slice of a combined buffer - used both standalone (e.g. crosscompare's own local-vs-peer comparison buffers, negotiate's own extra DATA payload) and internally by ab_gp_channel_payload_encode_ab_sample() below.

Parameters

id	A collector id previously returned by ab_gp_channel_payload_register_collector().
out	Destination, exactly that collector's own registered wire_size bytes. Must not be NULL.
items	Source array for that collector's own encode_fn. Must not be NULL.

Definition at line 77 of file ab_gp_channel_payload.c.

ab_gp_channel_payload_decode_collector()

void ab_gp_channel_payload_decode_collector	(	ab_gp_channel_payload_collector_id_t	id,
		const uint8_t *	in,
		void *	out_items )

Decodes one collector's own items - see ab_gp_channel_payload_encode_collector() (same contract, reversed).

Definition at line 88 of file ab_gp_channel_payload.c.

ab_gp_channel_payload_encode_ab_sample()

void ab_gp_channel_payload_encode_ab_sample	(	uint8_t	out[AB_SAMPLE_WIRE_SIZE],
		uint32_t	cycle,
		const void *const	sources[AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS] )

Encodes an A<->B peer-link sample: {cycle, every registered collector's own bytes in registration order, CRC-64 of the preceding bytes} - same "compute over everything but the CRC field itself" convention as rte_checksum_vital_message_create().

Parameters

out	Destination, exactly AB_SAMPLE_WIRE_SIZE bytes.
cycle	This channel's own cycle number.
sources	One source-array pointer per registered collector, indexed by collector id (e.g. sources[ab_gp_train_payload_collector_id()] = ctx->sessions) - unused trailing entries must be NULL.

Definition at line 99 of file ab_gp_channel_payload.c.

ab_gp_channel_payload_decode_ab_sample()

rte_status_t ab_gp_channel_payload_decode_ab_sample	(	uint8_t	in[AB_SAMPLE_WIRE_SIZE],
		uint32_t *	out_cycle,
		void *const	dests[AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS] )

Decodes and CRC-64-verifies an A<->B peer-link sample.

Parameters

dests

One destination-array pointer per registered collector, same indexing convention as ab_gp_channel_payload_encode_ab_sample()'s own sources.

Returns

RTE_STATUS_OK with out_cycle/dests populated if the trailing CRC-64 matches the bytes actually received; RTE_STATUS_DATA_CORRUPTION if it does not (the caller must not trust out_cycle/dests in that case - they are left unmodified); RTE_STATUS_INVALID_PARAM for a malformed buffer.

Definition at line 117 of file ab_gp_channel_payload.c.