cdi_avm_payloads_api.c File Reference

This file implements the AVM payloads API. More...

#include "cdi_avm_payloads_api.h"
#include "cdi_os_api.h"
#include "anc_payloads.h"
#include <assert.h>
#include <stdint.h>
#include <stdio.h>
#include <string.h>

Functions
static void *	CopyToLinearBuffer (CdiSgList const *sgl_ptr)
static CdiReturnStatus	PrecheckAncillaryDataPayload (const char *buffer_ptr, int payload_size_in_bytes)
static int	CopyInternalToPublicPacket (CdiAvmAncillaryDataPacket *dest_packet_ptr, const struct AncillaryDataPacket *source_packet_ptr)
static void	CopyPublicToInternalPacket (struct AncillaryDataPacket *dest_packet_ptr, const CdiAvmAncillaryDataPacket *source_packet_ptr)
int	CdiAvmCopyAncillaryDataPacket (CdiAvmAncillaryDataPacket *dest_packet_ptr, const CdiAvmAncillaryDataPacket *source_packet_ptr)
int	CdiAvmGetAncillaryDataPayloadSize (uint16_t num_anc_packets, uint8_t data_counts[])
CdiReturnStatus	CdiAvmPacketizeAncillaryData (CdiAvmPacketizeAncCallback *produce_next_packet_ptr, CdiFieldKind field_kind, void *context_ptr, char *buffer_ptr, int *size_in_bytes_ptr)
CdiReturnStatus	CdiAvmUnpacketizeAncillaryData (const CdiSgList *sgl_ptr, CdiAvmUnpacketizeAncCallback *consume_next_packet_ptr, void *context_ptr)

Detailed Description

This file implements the AVM payloads API.

Function Documentation

CdiAvmCopyAncillaryDataPacket()

int CdiAvmCopyAncillaryDataPacket	(	CdiAvmAncillaryDataPacket *	dest_packet_ptr,
		const CdiAvmAncillaryDataPacket *	source_packet_ptr )

Copy function. Only exists for testing.

Parameters

dest_packet_ptr	Destination packet to copy to.
source_packet_ptr	Source packet to copy from.

Returns

Number of parity errors (must be zero).

CdiAvmGetAncillaryDataPayloadSize()

int CdiAvmGetAncillaryDataPayloadSize	(	uint16_t	num_anc_packets,
		uint8_t	data_counts[] )

Calculate the buffer size needed to write an ancillary data payload.

Parameters

num_anc_packets	The number of ancillary data packets.
data_counts	Number of user data words for each prospective ancillary data packet (see CdiAvmAncillaryDataPacket).

Returns

Required buffer size in bytes.

CdiAvmPacketizeAncillaryData()

CdiReturnStatus CdiAvmPacketizeAncillaryData	(	CdiAvmPacketizeAncCallback *	produce_next_packet_ptr,
		CdiFieldKind	field_kind,
		void *	context_ptr,
		char *	buffer_ptr,
		int *	size_in_bytes_ptr )

Generate an ancillary data payload in the provided buffer. For each ancillary data packet the application's callback returns a pointer to an CdiAvmAncillaryDataPacket object; it returns NULL when the payload is complete. The packets produced by the callback are encoded in order. The whole payload is prefixed with a two-word header. See https://cdi.elemental.com/specs/baseline-ancillary-data for the payload format.

The provided buffer must be large enough to hold the encoded data. When the number of user data words of all ancillary data packets in the payload is known in advance, CdiAvmGetAncillaryDataPayloadSize may be used to compute the required buffer size.

Parameters

produce_next_packet_ptr	Callback provided by the application, producing next ancillary data packet to encode.
field_kind	Field kind of this payload. See CdiFieldKind.
context_ptr	Pointer to user-defined data to keep track of state.
buffer_ptr	Pointer to payload buffer.
size_in_bytes_ptr	Points to size in bytes of payload buffer. Points to size of payload on successful return.

Returns

Status code indicating success or failure.

CdiAvmUnpacketizeAncillaryData()

CdiReturnStatus CdiAvmUnpacketizeAncillaryData	(	const CdiSgList *	sgl_ptr,
		CdiAvmUnpacketizeAncCallback *	consume_next_packet_ptr,
		void *	context_ptr )

Decode an ancillary data payload from the provided buffer and pass decoded ancillary data packets to the provided callback function for processing. If the payload cannot be decoded then kCdiInvalidPayload is returned. A return code of kCdiStatusRxPayloadError indicates that the payload was decoded with parity or checksum errors detected.

Parameters

sgl_ptr	Pointer to payload buffer.
consume_next_packet_ptr	Callback provided by the application, consuming next decoded ancillary data packet.
context_ptr	Pointer to user-defined data to keep track of state.

Returns

Status code indicating success or failure.

CopyInternalToPublicPacket()

static int CopyInternalToPublicPacket ( CdiAvmAncillaryDataPacket * dest_packet_ptr, const struct AncillaryDataPacket * source_packet_ptr )

static

Copy internal packet structure to public-facing API. Count number of parity errors in source.

Parameters

dest_packet_ptr	Destination packet to copy to.
source_packet_ptr	Source packet to copy from.

Returns

Number of user data parity errors detected in source packet.

CopyPublicToInternalPacket()

static void CopyPublicToInternalPacket ( struct AncillaryDataPacket * dest_packet_ptr, const CdiAvmAncillaryDataPacket * source_packet_ptr )

static

Copy public packet data to internal packet structure and add parity bits to 8-bit user data.

Parameters

dest_packet_ptr	Destination packet to copy to.
source_packet_ptr	Source packet to copy from.

CopyToLinearBuffer()

static void * CopyToLinearBuffer ( CdiSgList const * sgl_ptr )

static

Copy SGL buffer contents to a linear buffer.

Parameters

sgl_ptr

Pointer to SGL.

Returns

Pointer to linear buffer. Caller needs to free buffer.

PrecheckAncillaryDataPayload()

static CdiReturnStatus PrecheckAncillaryDataPayload ( const char * buffer_ptr, int payload_size_in_bytes )

static

Helper function for CdiAvmUnpacketizeAncillaryDataPayload. Decodes the payload header and checks that the payload may be decoded without exceeding the specified payload size.

Parameters

buffer_ptr	Pointer to the payload buffer.
payload_size_in_bytes	Size of the payload.

Returns

Return code indicating success or failure.