ab_gp_channel_payload.c File Reference

Generic collector registry + AB_SAMPLE framing - see ab_gp_channel_payload.h. More...

#include "ab_gp_channel_payload.h"
#include "rte/utils/buffer/rte_buffer.h"
#include "rte/redundancy/checksum/rte_checksum.h"
#include "rte/utils/lifecycle/rte_lifecycle.h"
#include "../../common/common_config.h"

Include dependency graph for ab_gp_channel_payload.c:

Go to the source code of this file.

Data Structures
struct	ab_gp_channel_payload_collector_t

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.

Variables
static ab_gp_channel_payload_collector_t	g_collectors [AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS]
static uint32_t	g_collector_count = 0U
static uint32_t	g_payload_size = 0U

Detailed Description

Generic collector registry + AB_SAMPLE framing - see ab_gp_channel_payload.h.

Definition in file ab_gp_channel_payload.c.

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

Global variables declarations Local function declarations Global functions

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.

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.

Variable Documentation

g_collectors

ab_gp_channel_payload_collector_t g_collectors[AB_GP_CHANNEL_PAYLOAD_MAX_COLLECTORS]

static

Local variables declarations

Definition at line 32 of file ab_gp_channel_payload.c.

g_collector_count

uint32_t g_collector_count = 0U

static

Definition at line 33 of file ab_gp_channel_payload.c.

g_payload_size

uint32_t g_payload_size = 0U

static

Definition at line 34 of file ab_gp_channel_payload.c.