ccc_mac.c File Reference

— UWB MAC: hopping sequence, SP0 frame codec, ranging schedule. More...

#include <errno.h>
#include <string.h>
#include "ccc_mac.h"

Include dependency graph for ccc_mac.c:

Macros
#define	CCC_HOP_MODULUS   65521u
	Default-hopping modulus, 2^16 - 15 (prime).

Functions
uint16_t	ccc_hop_round_index (uint32_t block_index, uint32_t hop_key_rw, uint32_t n_round)
	Default hopping round index S(i) in [0, n_round) for a ranging block.
static void	put_le16 (uint8_t *p, uint16_t v)
	Store a uint16 little-endian.
static void	put_le32 (uint8_t *p, uint32_t v)
	Store a uint32 little-endian.
static uint16_t	get_le16 (const uint8_t *p)
	Load a uint16 little-endian.
static uint32_t	get_le32 (const uint8_t *p)
	Load a uint32 little-endian.
static bool	mhr_vendor_oui_ok (const uint8_t *p)
	True if the 3-byte little-endian OUI at p is the CCC or Aliro OUI (both accepted).
int	ccc_build_mhr (const struct ccc_mhr_fields *f, uint8_t out[CCC_MHR_LEN])
	Build the 23-byte SP0 MHR little-endian on the wire.
int	ccc_parse_mhr (const uint8_t in[CCC_MHR_LEN], struct ccc_mhr_fields *f)
	Parse and validate a 23-byte SP0 MHR, extracting variable fields.
int	ccc_pre_poll_pack (const struct ccc_pre_poll *p, uint8_t out[CCC_PRE_POLL_LEN])
	Pack a Pre-POLL payload little-endian.
int	ccc_pre_poll_parse (const uint8_t in[CCC_PRE_POLL_LEN], struct ccc_pre_poll *p)
	Parse a 13-byte Pre-POLL payload.
int	ccc_final_data_pack (const struct ccc_final_data *f, uint8_t *out, size_t cap, size_t *len)
	Pack a Final_Data payload little-endian.
int	ccc_final_data_parse (const uint8_t *in, size_t len, struct ccc_final_data *f)
	Parse a Final_Data payload.
static uint32_t	slot_offset (const struct ccc_ran_params *p, enum ccc_slot slot, uint8_t responder)
	STS-index offset of a slot within its ranging round.
uint16_t	ccc_block_round (const struct ccc_ran_params *p, uint32_t block)
	The ranging round a block uses (block 0 uses round 0; continuous hopping uses S(i) for i>=1).
uint32_t	ccc_slot_sts_index (const struct ccc_ran_params *p, uint32_t block, uint16_t round, enum ccc_slot slot, uint8_t responder)
	STS index for one slot of a ranging round (wraps mod 2^32).
struct ccc_hop_decision	ccc_initiator_next_hop (const struct ccc_ran_params *p, uint32_t block)
	The initiator's hop decision for the block after block, written into its Final_Data.
uint32_t	ccc_ds_twr_tof (const struct ccc_ds_twr *t)
	DS-TWR one-way time-of-flight in timestamp ticks.
int	ccc_responder_ds_twr (const struct ccc_final_data *fd, uint8_t responder, uint32_t t_reply1, uint32_t t_round2, struct ccc_ds_twr *out)
	Assemble the DS-TWR intervals at the responder from a received Final_Data.
bool	ccc_ursk_exhausted (const struct ccc_ran_params *p, uint32_t block)
	Whether the current URSK is exhausted for a ranging block (true once its highest STS index would exceed 2^31-1).

Detailed Description

— UWB MAC: hopping sequence, SP0 frame codec, ranging schedule.

Function Documentation

ccc_block_round()

uint16_t ccc_block_round	(	const struct ccc_ran_params *	p,
		uint32_t	block
	)

The ranging round a block uses (block 0 uses round 0; continuous hopping uses S(i) for i>=1).

Parameters

p	Ranging parameters.
block	Block index.

Returns

Round index in [0, n_round).

ccc_build_mhr()

int ccc_build_mhr	(	const struct ccc_mhr_fields *	f,
		uint8_t	out[CCC_MHR_LEN]
	)

Build the 23-byte SP0 MHR little-endian on the wire.

Build the 23-byte SP0 MHR (little-endian on the wire).

Parameters

f	MHR fields (destination address, frame counter, key source, message ID, payload length).
out	Output buffer of at least CCC_MHR_LEN bytes.

Returns

0 on success, -EINVAL if inputs are null.

ccc_ds_twr_tof()

uint32_t ccc_ds_twr_tof

(

const struct ccc_ds_twr *

t

)

DS-TWR one-way time-of-flight in timestamp ticks.

DS-TWR one-way time-of-flight in timestamp ticks (0 if the denominator is 0).

Parameters

t	DS-TWR intervals (round-trip and reply times at both ends).

Returns

Time-of-flight in ticks, or 0 if the denominator is 0 or input is null.

ccc_final_data_pack()

int ccc_final_data_pack	(	const struct ccc_final_data *	f,
		uint8_t *	out,
		size_t	cap,
		size_t *	len
	)

Pack a Final_Data payload little-endian.

Parameters

f	Final_Data structure (session ID, ranging block, hop flag, round index, STS index, timestamp, responder list).
out	Output buffer.
cap	Capacity of output buffer.
len	Output: number of bytes written.

Returns

0 on success, -EINVAL if inputs are null, responder count exceeds CCC_MAX_RESPONDERS, or buffer is too small.

ccc_final_data_parse()

int ccc_final_data_parse	(	const uint8_t *	in,
		size_t	len,
		struct ccc_final_data *	f
	)

Parse a Final_Data payload.

Parse a Final_Data payload (-EINVAL if length is inconsistent with num_responders).

Parameters

in	Input buffer.
len	Length of input buffer.
f	Output structure to hold parsed fields (session ID, ranging block, hop flag, round index, STS index, timestamp, responder list).

Returns

0 on success, -EINVAL if inputs are null, input length is inconsistent with responder count, or responder count exceeds CCC_MAX_RESPONDERS.

ccc_hop_round_index()

uint16_t ccc_hop_round_index	(	uint32_t	block_index,
		uint32_t	hop_key_rw,
		uint32_t	n_round
	)

Default hopping round index S(i) in [0, n_round) for a ranging block.

Default hopping round index S(i) in [0, n_round) for a ranging block, keyed by HOP_Key_RW.

Parameters

block_index	Block index i.
hop_key_rw	HOP_Key_RW value keying the hop calculation.
n_round	Total number of ranging rounds.

Returns

Round index in [0, n_round).

ccc_initiator_next_hop()

struct ccc_hop_decision ccc_initiator_next_hop	(	const struct ccc_ran_params *	p,
		uint32_t	block
	)

The initiator's hop decision for the block after block, written into its Final_Data.

Parameters

p	Ranging parameters.
block	Block index.

Returns

Hop decision (hop flag and next round index); both zero if hopping is disabled or params are null.

ccc_parse_mhr()

int ccc_parse_mhr	(	const uint8_t	in[CCC_MHR_LEN],
		struct ccc_mhr_fields *	f
	)

Parse and validate a 23-byte SP0 MHR, extracting variable fields.

Parse and validate a 23-byte SP0 MHR, extracting the variable fields (-EINVAL on mismatch).

Parameters

in	Input buffer of exactly CCC_MHR_LEN bytes.
f	Output structure to hold parsed fields (destination address, frame counter, key source, message ID, payload length).

Returns

0 on success, -EINVAL on mismatch or null input.

ccc_pre_poll_pack()

int ccc_pre_poll_pack	(	const struct ccc_pre_poll *	p,
		uint8_t	out[CCC_PRE_POLL_LEN]
	)

Pack a Pre-POLL payload little-endian.

Parameters

p	Pre-POLL structure (session ID, STS index, ranging block, hop flag, round index).
out	Output buffer of at least CCC_PRE_POLL_LEN bytes.

Returns

0 on success, -EINVAL if inputs are null.

ccc_pre_poll_parse()

int ccc_pre_poll_parse	(	const uint8_t	in[CCC_PRE_POLL_LEN],
		struct ccc_pre_poll *	p
	)

Parse a 13-byte Pre-POLL payload.

Parameters

in	Input buffer of exactly CCC_PRE_POLL_LEN bytes.
p	Output structure to hold parsed fields (session ID, STS index, ranging block, hop flag, round index).

Returns

0 on success, -EINVAL if inputs are null.

ccc_slot_sts_index()

uint32_t ccc_slot_sts_index	(	const struct ccc_ran_params *	p,
		uint32_t	block,
		uint16_t	round,
		enum ccc_slot	slot,
		uint8_t	responder
	)

STS index for one slot of a ranging round (wraps mod 2^32).

STS index for one slot of a ranging round (uint32 wraps mod 2^32).

Parameters

p	Ranging parameters.
block	Block index.
round	Round index.
slot	Slot type (POLL, Response, or Final).
responder	Responder index.

Returns

STS index for the slot.