ccc_mac.h File Reference

— CCC UWB MAC layer: ranging-round scheduling, SP0 frame codec, DS-TWR. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "ccc_kdf.h"

Include dependency graph for ccc_mac.h:

Go to the source code of this file.

Data Structures
struct	ccc_mhr_fields
	The per-frame-variable fields of an SP0 MHR (fixed fields are built in by ccc_build_mhr). More...
struct	ccc_pre_poll
	Pre-POLL request message parameters. More...
struct	ccc_responder_ts
	One responder's timestamp record in a Final_Data message. More...
struct	ccc_final_data
	Final_Data message parameters. More...
struct	ccc_ran_params
	Per-session ranging schedule parameters (negotiated in setup). More...
struct	ccc_hop_decision
	The initiator's next-block hop decision, carried in Final_Data. More...
struct	ccc_ds_twr
	The four DS-TWR intervals, in ranging-timestamp ticks (uint32, wrap mod 2^32). More...

Macros
#define	CCC_MHR_LEN   23
	SP0 MHR length, bytes.
#define	CCC_PRE_POLL_LEN   13
	Pre-POLL MAC payload length, bytes.
#define	CCC_FINAL_DATA_HDR_LEN   18
	Final_Data payload length before the responder records, bytes.
#define	CCC_RESPONDER_LEN   7
	One responder timestamp record in a Final_Data payload, bytes.
#define	CCC_MAX_RESPONDERS   10
	Max responders in one Final_Data (127-byte payload cap).
#define	CCC_MSG_ID_PRE_POLL   0x01u
	Vendor Specific Information message ID for Pre-POLL.
#define	CCC_MSG_ID_FINAL_DATA   0x02u
	Vendor Specific Information message ID for Final_Data.
#define	CCC_STS_INDEX_MAX   0x7FFFFFFFu
	STS index at which the URSK must be discarded: 2^31 − 1.

Enumerations
enum	ccc_hop_mode { CCC_HOP_NONE = 0 , CCC_HOP_CONTINUOUS = 1 }
	Hopping mode. More...
enum	ccc_slot {   CCC_SLOT_PRE_POLL , CCC_SLOT_POLL , CCC_SLOT_RESPONSE , CCC_SLOT_FINAL ,   CCC_SLOT_FINAL_DATA }
	Slot role within a ranging round. More...

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, keyed by HOP_Key_RW.
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 the variable fields (-EINVAL on mismatch).
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 (-EINVAL if length is inconsistent with num_responders).
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 (uint32 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 (0 if the denominator is 0).
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

— CCC UWB MAC layer: ranging-round scheduling, SP0 frame codec, DS-TWR.

Enumeration Type Documentation

ccc_hop_mode

enum ccc_hop_mode

Hopping mode.

Adaptive (interference-driven) is out of scope.

Enumerator
CCC_HOP_NONE	No hopping: every block uses ranging round 0.
CCC_HOP_CONTINUOUS	Continuous hopping: block i uses round S(i).

ccc_slot

enum ccc_slot

Slot role within a ranging round.

Enumerator
CCC_SLOT_PRE_POLL	Slot 0 — SP0 data packet, initiator.
CCC_SLOT_POLL	Slot 1 — SP3 RFRAME, initiator.
CCC_SLOT_RESPONSE	Slots 2..1+N — SP3 RFRAME, responder l.
CCC_SLOT_FINAL	SP3 RFRAME, initiator.
CCC_SLOT_FINAL_DATA	SP0 data packet, initiator.

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 (0 if the denominator is 0).

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 (-EINVAL if length is inconsistent with num_responders).

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, keyed by HOP_Key_RW.

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 the variable fields (-EINVAL on mismatch).

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 (uint32 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.