TRXD (burst data) protocol: I/O-free PDU codec. More...

#include <stdint.h>
#include <stddef.h>
#include <osmocom/core/bits.h>
#include <osmocom/core/utils.h>

Data Structures
struct	osmo_trxd_burst_ind
	TRX -> L1: received burst indication (soft bits + measurements). More...

struct	osmo_trxd_burst_req
	L1 -> TRX: burst transmit request (hard bits). More...

struct	osmo_trxd_parse_state
	Parser state, keeping cross-PDU context for TRXDv2 batches. More...

Macros
#define	OSMO_TRXD_PDU_VER_MAX 2
	The highest TRXD PDU version supported by this library. More...

#define	OSMO_TRXD_BURST_LEN_GMSK 148
	GMSK modulated burst: 1 bit per symbol. More...

#define	OSMO_TRXD_BURST_LEN_8PSK 444
	8-PSK modulated burst: 3 bits per symbol More...

#define	OSMO_TRXD_BURST_LEN_MAX OSMO_TRXD_BURST_LEN_8PSK
	Maximum burst length in (soft-)bits. More...

#define	OSMO_TRXD_HDR_LEN_MAX 12
	Maximum single-PDU header size, in bytes: the TRXDv2 header (largest of all versions, either direction) plus the TDMA FN present on the first PDU of a datagram. More...

#define	OSMO_TRXD_MSG_BUF_SIZE (OSMO_TRXD_HDR_LEN_MAX + OSMO_TRXD_BURST_LEN_MAX)
	Recommended Rx/Tx socket buffer size, in bytes, for a single (non-batched) TRXD datagram: largest possible header plus the largest possible burst payload. More...

#define	OSMO_TRXD_F_NOPE_IND (1 << 0)
	no burst detected / idle indication More...

#define	OSMO_TRXD_F_NOPE_REQ OSMO_TRXD_F_NOPE_IND
	alias of OSMO_TRXD_F_NOPE_IND, reading cleaner in BURST.req context More...

#define	OSMO_TRXD_F_MOD_TYPE (1 << 1)
	'mod' is valid More...

#define	OSMO_TRXD_F_TS_INFO (1 << 2)
	'tsc_set'/'tsc' are valid More...

#define	OSMO_TRXD_F_CI_CB (1 << 3)
	'ci_cb' is valid More...

#define	OSMO_TRXD_F_TRX_NUM (1 << 4)
	'trx_num' is valid More...

#define	OSMO_TRXD_F_BATCH_IND (1 << 5)
	more PDUs follow in this datagram More...

#define	OSMO_TRXD_F_SHADOW_IND (1 << 6)
	burst received on a shadow (VAMOS) channel More...

#define	OSMO_TRXD_F_ACCESS_BURST (1 << 7)
	an Access Burst (RACH) More...

Enumerations
enum	osmo_trxd_mod_type { OSMO_TRXD_MOD_T_GMSK , OSMO_TRXD_MOD_T_8PSK , OSMO_TRXD_MOD_T_AQPSK }
	Modulation types (defined by the TRXDv2 MTS encoding, 3GPP TS 45.002) More...

Functions
void	osmo_trxd_parse_state_init (struct osmo_trxd_parse_state *st)
	Initialize a parser state; call before parsing each datagram. More...

int	osmo_trxd_burst_ind_parse (struct osmo_trxd_parse_state st, struct osmo_trxd_burst_ind bi, const uint8_t *buf, size_t buf_len)
	Parse one burst indication (TRX -> L1) PDU from the given buffer. More...

int	osmo_trxd_burst_req_parse (struct osmo_trxd_parse_state st, struct osmo_trxd_burst_req br, const uint8_t *buf, size_t buf_len)
	Parse one burst transmit request (L1 -> TRX) PDU from the given buffer. More...

int	osmo_trxd_burst_ind_build (struct msgb msg, uint8_t pdu_ver, const struct osmo_trxd_burst_ind bi)
	Append one encoded burst indication (TRX -> L1) PDU to the given msgb. More...

int	osmo_trxd_burst_req_build (struct msgb msg, uint8_t pdu_ver, const struct osmo_trxd_burst_req br)
	Append one encoded burst transmit request (L1 -> TRX) PDU to the given msgb. More...

void	osmo_trxd_build_fin (struct msgb *msg, uint8_t pdu_ver)
	Finalize a datagram built by osmo_trxd_burst_{ind,req}_build(). More...

const char *	osmo_trxd_burst_ind_name (const struct osmo_trxd_burst_ind *bi)
	Compose a human-readable representation of the given burst indication (for logging), store into a thread-local static buffer. More...

char *	osmo_trxd_burst_ind_name_buf (char buf, size_t buf_len, const struct osmo_trxd_burst_ind bi)
	Compose a human-readable representation of the given burst indication (for logging), store into the given buffer. More...

const char *	osmo_trxd_burst_req_name (const struct osmo_trxd_burst_req *br)
	Compose a human-readable representation of the given burst transmit request (for logging), store into a thread-local static buffer. More...

char *	osmo_trxd_burst_req_name_buf (char buf, size_t buf_len, const struct osmo_trxd_burst_req br)
	Compose a human-readable representation of the given burst transmit request (for logging), store into the given buffer. More...

static const char *	osmo_trxd_mod_type_name (enum osmo_trxd_mod_type mod)

Variables
const struct value_string	osmo_trxd_mod_type_names []

Detailed Description

TRXD (burst data) protocol: I/O-free PDU codec.

Macro Definition Documentation

◆ OSMO_TRXD_BURST_LEN_8PSK

#define OSMO_TRXD_BURST_LEN_8PSK 444

8-PSK modulated burst: 3 bits per symbol

◆ OSMO_TRXD_BURST_LEN_GMSK

#define OSMO_TRXD_BURST_LEN_GMSK 148

GMSK modulated burst: 1 bit per symbol.

◆ OSMO_TRXD_BURST_LEN_MAX

#define OSMO_TRXD_BURST_LEN_MAX OSMO_TRXD_BURST_LEN_8PSK

Maximum burst length in (soft-)bits.

◆ OSMO_TRXD_F_ACCESS_BURST

#define OSMO_TRXD_F_ACCESS_BURST (1 << 7)

an Access Burst (RACH)

◆ OSMO_TRXD_F_BATCH_IND

#define OSMO_TRXD_F_BATCH_IND (1 << 5)

more PDUs follow in this datagram

◆ OSMO_TRXD_F_CI_CB

#define OSMO_TRXD_F_CI_CB (1 << 3)

'ci_cb' is valid

◆ OSMO_TRXD_F_MOD_TYPE

#define OSMO_TRXD_F_MOD_TYPE (1 << 1)

'mod' is valid

◆ OSMO_TRXD_F_NOPE_IND

#define OSMO_TRXD_F_NOPE_IND (1 << 0)

no burst detected / idle indication

◆ OSMO_TRXD_F_NOPE_REQ

#define OSMO_TRXD_F_NOPE_REQ OSMO_TRXD_F_NOPE_IND

alias of OSMO_TRXD_F_NOPE_IND, reading cleaner in BURST.req context

◆ OSMO_TRXD_F_SHADOW_IND

#define OSMO_TRXD_F_SHADOW_IND (1 << 6)

burst received on a shadow (VAMOS) channel

◆ OSMO_TRXD_F_TRX_NUM

#define OSMO_TRXD_F_TRX_NUM (1 << 4)

'trx_num' is valid

◆ OSMO_TRXD_F_TS_INFO

#define OSMO_TRXD_F_TS_INFO (1 << 2)

'tsc_set'/'tsc' are valid

◆ OSMO_TRXD_HDR_LEN_MAX

#define OSMO_TRXD_HDR_LEN_MAX 12

Maximum single-PDU header size, in bytes: the TRXDv2 header (largest of all versions, either direction) plus the TDMA FN present on the first PDU of a datagram.

◆ OSMO_TRXD_MSG_BUF_SIZE

#define OSMO_TRXD_MSG_BUF_SIZE (OSMO_TRXD_HDR_LEN_MAX + OSMO_TRXD_BURST_LEN_MAX)

Recommended Rx/Tx socket buffer size, in bytes, for a single (non-batched) TRXD datagram: largest possible header plus the largest possible burst payload.

◆ OSMO_TRXD_PDU_VER_MAX

#define OSMO_TRXD_PDU_VER_MAX 2

The highest TRXD PDU version supported by this library.

Enumeration Type Documentation

◆ osmo_trxd_mod_type

enum osmo_trxd_mod_type

Modulation types (defined by the TRXDv2 MTS encoding, 3GPP TS 45.002)

Enumerator
OSMO_TRXD_MOD_T_GMSK
OSMO_TRXD_MOD_T_8PSK
OSMO_TRXD_MOD_T_AQPSK

Function Documentation

◆ osmo_trxd_build_fin()

void osmo_trxd_build_fin	(	struct msgb *	msg,
		uint8_t	pdu_ver
	)

Finalize a datagram built by osmo_trxd_burst_{ind,req}_build().

Parameters

[in,out]	msg	message buffer holding the encoded PDU(s)
[in]	pdu_ver	TRXD PDU version in use

Referenced by trx_ep_data_tx_flush().

◆ osmo_trxd_burst_ind_build()

int osmo_trxd_burst_ind_build	(	struct msgb *	msg,
		uint8_t	pdu_ver,
		const struct osmo_trxd_burst_ind *	bi
	)

Append one encoded burst indication (TRX -> L1) PDU to the given msgb.

For TRXDv2, PDU batching works by calling this function repeatedly on the same msgb; call osmo_trxd_build_fin() once the datagram is complete (it clears the BATCH.ind bit of the last PDU).

Parameters

[in,out]	msg	destination message buffer
[in]	pdu_ver	TRXD PDU version to encode
[in]	bi	burst indication to be encoded

Returns: 0 on success; negative on error. Note that TRXDv0 has no MTS field, so a NOPE.ind is encoded as a header-only PDU with the burst payload omitted.

References osmo_trxd_burst_ind::burst, osmo_trxd_burst_ind::burst_len, osmo_trxd_burst_ind::ci_cb, osmo_trxd_burst_ind::flags, osmo_trxd_burst_ind::fn, OSMO_TRXD_F_NOPE_IND, OSMO_TRXD_F_SHADOW_IND, osmo_trxd_burst_ind::rssi, soft_bits_build(), osmo_trxd_burst_ind::tn, osmo_trxd_burst_ind::toa256, osmo_trxd_burst_ind::trx_num, TRXD_IND_V0HDR_LEN, TRXD_IND_V1HDR_LEN, TRXD_IND_V2HDR_LEN, and trxd_mts_build_ind().

Referenced by osmo_trx_ep_send_burst_ind().

◆ osmo_trxd_burst_ind_name()

const char * osmo_trxd_burst_ind_name ( const struct osmo_trxd_burst_ind * bi )

Compose a human-readable representation of the given burst indication (for logging), store into a thread-local static buffer.

Parameters

[in] bi BURST.ind to get a human-readable representation of

Returns: pointer to a thread-local static buffer

References osmo_trxd_burst_ind_name_buf().

◆ osmo_trxd_burst_ind_name_buf()

char * osmo_trxd_burst_ind_name_buf	(	char *	buf,
		size_t	buf_len,
		const struct osmo_trxd_burst_ind *	bi
	)

Compose a human-readable representation of the given burst indication (for logging), store into the given buffer.

Parameters

[out]	buf	output buffer to store the result
[in]	buf_len	size of the output buffer
[in]	bi	BURST.ind to get a human-readable representation of

Returns: pointer to the given buffer

References osmo_trxd_burst_ind::burst_len, osmo_trxd_burst_ind::ci_cb, osmo_trxd_burst_ind::flags, osmo_trxd_burst_ind::fn, osmo_trxd_burst_ind::mod, OSMO_TRXD_F_CI_CB, OSMO_TRXD_F_MOD_TYPE, OSMO_TRXD_F_NOPE_IND, OSMO_TRXD_F_TRX_NUM, OSMO_TRXD_F_TS_INFO, osmo_trxd_mod_type_name(), osmo_trxd_burst_ind::rssi, osmo_trxd_burst_ind::tn, osmo_trxd_burst_ind::toa256, osmo_trxd_burst_ind::trx_num, osmo_trxd_burst_ind::tsc, and osmo_trxd_burst_ind::tsc_set.

Referenced by osmo_trxd_burst_ind_name().

◆ osmo_trxd_burst_ind_parse()

int osmo_trxd_burst_ind_parse	(	struct osmo_trxd_parse_state *	st,
		struct osmo_trxd_burst_ind *	bi,
		const uint8_t *	buf,
		size_t	buf_len
	)

Parse one burst indication (TRX -> L1) PDU from the given buffer.

The PDU version is parsed from the first PDU of a datagram and kept in st. Starting from TRXDv2, a datagram may batch multiple PDUs: call this function repeatedly on the remaining buffer as long as the parsed PDU has OSMO_TRXD_F_BATCH_IND set in bi->flags.

Parameters

[in,out]	st	parser state (see osmo_trxd_parse_state_init())
[out]	bi	parsed burst indication
[in]	buf	buffer positioned at the beginning of a PDU
[in]	buf_len	remaining length of the buffer

Returns: number of consumed bytes on success; negative on error

References osmo_trxd_burst_ind::burst, osmo_trxd_burst_ind::burst_len, burst_len_by_mod(), osmo_trxd_burst_ind::flags, osmo_trxd_burst_ind::fn, osmo_trxd_burst_ind::mod, osmo_trxd_parse_state::num_pdus, OSMO_TRXD_F_NOPE_IND, OSMO_TRXD_PDU_VER_MAX, osmo_trxd_parse_state::pdu_ver, soft_bits_parse(), trxd_burst_ind_parse_v0(), trxd_burst_ind_parse_v1(), trxd_burst_ind_parse_v2(), TRXD_IND_V0HDR_LEN, TRXD_IND_V1HDR_LEN, and TRXD_IND_V2HDR_LEN.

Referenced by trx_ep_data_read_cb().

◆ osmo_trxd_burst_req_build()

int osmo_trxd_burst_req_build	(	struct msgb *	msg,
		uint8_t	pdu_ver,
		const struct osmo_trxd_burst_req *	br
	)

Append one encoded burst transmit request (L1 -> TRX) PDU to the given msgb.

For TRXDv2, PDU batching works by calling this function repeatedly on the same msgb; call osmo_trxd_build_fin() once the datagram is complete (it clears the BATCH.ind bit of the last PDU).

Parameters

[in,out]	msg	destination message buffer
[in]	pdu_ver	TRXD PDU version to encode
[in]	br	burst transmit request to be encoded

Returns: 0 on success; negative on error

References osmo_trxd_burst_req::att, osmo_trxd_burst_req::burst, osmo_trxd_burst_req::burst_len, osmo_trxd_burst_req::flags, osmo_trxd_burst_req::fn, OSMO_TRXD_F_NOPE_REQ, osmo_trxd_burst_req::scpir, osmo_trxd_burst_req::tn, osmo_trxd_burst_req::trx_num, trxd_mts_build_req(), TRXD_REQ_V01HDR_LEN, and TRXD_REQ_V2HDR_LEN.

Referenced by osmo_trx_ep_send_burst_req().

◆ osmo_trxd_burst_req_name()

const char * osmo_trxd_burst_req_name ( const struct osmo_trxd_burst_req * br )

Compose a human-readable representation of the given burst transmit request (for logging), store into a thread-local static buffer.

Parameters

[in] br BURST.req to get a human-readable representation of

Returns: pointer to a thread-local static buffer

References osmo_trxd_burst_req_name_buf().

◆ osmo_trxd_burst_req_name_buf()

char * osmo_trxd_burst_req_name_buf	(	char *	buf,
		size_t	buf_len,
		const struct osmo_trxd_burst_req *	br
	)

Compose a human-readable representation of the given burst transmit request (for logging), store into the given buffer.

Parameters

[out]	buf	output buffer to store the result
[in]	buf_len	size of the output buffer
[in]	br	BURST.req to get a human-readable representation of

Returns: pointer to the given buffer

References osmo_trxd_burst_req::att, osmo_trxd_burst_req::burst_len, osmo_trxd_burst_req::flags, osmo_trxd_burst_req::fn, osmo_trxd_burst_req::mod, OSMO_TRXD_F_MOD_TYPE, OSMO_TRXD_F_NOPE_REQ, OSMO_TRXD_F_TRX_NUM, OSMO_TRXD_F_TS_INFO, osmo_trxd_mod_type_name(), osmo_trxd_burst_req::tn, osmo_trxd_burst_req::trx_num, osmo_trxd_burst_req::tsc, and osmo_trxd_burst_req::tsc_set.

Referenced by osmo_trxd_burst_req_name().

◆ osmo_trxd_burst_req_parse()

int osmo_trxd_burst_req_parse	(	struct osmo_trxd_parse_state *	st,
		struct osmo_trxd_burst_req *	br,
		const uint8_t *	buf,
		size_t	buf_len
	)

Parse one burst transmit request (L1 -> TRX) PDU from the given buffer.

The PDU version is parsed from the first PDU of a datagram and kept in st. Starting from TRXDv2, a datagram may batch multiple PDUs: call this function repeatedly on the remaining buffer as long as the parsed PDU has OSMO_TRXD_F_BATCH_IND set in br->flags.

Parameters

[in,out]	st	parser state (see osmo_trxd_parse_state_init())
[out]	br	parsed burst transmit request
[in]	buf	buffer positioned at the beginning of a PDU
[in]	buf_len	remaining length of the buffer

Returns: number of consumed bytes on success; negative on error

References osmo_trxd_burst_req::fn, osmo_trxd_parse_state::num_pdus, OSMO_TRXD_PDU_VER_MAX, osmo_trxd_parse_state::pdu_ver, trxd_burst_req_parse_v01(), trxd_burst_req_parse_v2(), TRXD_REQ_V01HDR_LEN, and TRXD_REQ_V2HDR_LEN.

Referenced by trx_ep_data_read_cb().

◆ osmo_trxd_mod_type_name()

static const char * osmo_trxd_mod_type_name ( enum osmo_trxd_mod_type mod )

inlinestatic

References osmo_trxd_mod_type_names.

Referenced by osmo_trxd_burst_ind_name_buf(), and osmo_trxd_burst_req_name_buf().

◆ osmo_trxd_parse_state_init()

void osmo_trxd_parse_state_init ( struct osmo_trxd_parse_state * st )

Initialize a parser state; call before parsing each datagram.

Parameters

[out] st parser state to be initialized

Referenced by trx_ep_data_read_cb().

Variable Documentation

◆ osmo_trxd_mod_type_names

const struct value_string osmo_trxd_mod_type_names[]

extern

Referenced by osmo_trxd_mod_type_name().

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ OSMO_TRXD_BURST_LEN_8PSK

◆ OSMO_TRXD_BURST_LEN_GMSK

◆ OSMO_TRXD_BURST_LEN_MAX

◆ OSMO_TRXD_F_ACCESS_BURST

◆ OSMO_TRXD_F_BATCH_IND

◆ OSMO_TRXD_F_CI_CB

◆ OSMO_TRXD_F_MOD_TYPE

◆ OSMO_TRXD_F_NOPE_IND

◆ OSMO_TRXD_F_NOPE_REQ

◆ OSMO_TRXD_F_SHADOW_IND

◆ OSMO_TRXD_F_TRX_NUM

◆ OSMO_TRXD_F_TS_INFO

◆ OSMO_TRXD_HDR_LEN_MAX

◆ OSMO_TRXD_MSG_BUF_SIZE

◆ OSMO_TRXD_PDU_VER_MAX

Enumeration Type Documentation

◆ osmo_trxd_mod_type

Function Documentation

◆ osmo_trxd_build_fin()

◆ osmo_trxd_burst_ind_build()

◆ osmo_trxd_burst_ind_name()

◆ osmo_trxd_burst_ind_name_buf()

◆ osmo_trxd_burst_ind_parse()

◆ osmo_trxd_burst_req_build()

◆ osmo_trxd_burst_req_name()

◆ osmo_trxd_burst_req_name_buf()

◆ osmo_trxd_burst_req_parse()

◆ osmo_trxd_mod_type_name()

◆ osmo_trxd_parse_state_init()

Variable Documentation

◆ osmo_trxd_mod_type_names