trxc.h File Reference

TRXC (control) protocol and clock indications: I/O-free message codec. More...

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

Go to the source code of this file.

Data Structures
struct	osmo_trxc_msg
	A single de-/serialized TRXC message. More...
struct	osmo_trxc_setslot_tsc
	One "C<tsc>/S<tsc_set>" override, as used by SETSLOT for (VAMOS) sub-channels that don't use the endpoint-wide TSC (SETTSC). More...
struct	osmo_trxc_setslot
	Parsed SETSLOT parameters. More...

Macros
#define	OSMO_TRXC_CMD_LEN_MAX   32
	Maximum length of a command verb (incl. More...
#define	OSMO_TRXC_MSG_BUF_SIZE   1500
	Recommended TRXC socket read/send buffer size. More...
#define	OSMO_TRXC_PARAMS_LEN_MAX   (OSMO_TRXC_MSG_BUF_SIZE - OSMO_TRXC_CMD_LEN_MAX - 32)
	Maximum length of the parameters string (incl. More...
#define	OSMO_TRXC_CMD_POWERON   "POWERON"
#define	OSMO_TRXC_CMD_POWEROFF   "POWEROFF"
#define	OSMO_TRXC_CMD_RXTUNE   "RXTUNE"
#define	OSMO_TRXC_CMD_TXTUNE   "TXTUNE"
#define	OSMO_TRXC_CMD_SETSLOT   "SETSLOT"
#define	OSMO_TRXC_CMD_SETTSC   "SETTSC"
#define	OSMO_TRXC_CMD_SETBSIC   "SETBSIC"
#define	OSMO_TRXC_CMD_SETPOWER   "SETPOWER"
#define	OSMO_TRXC_CMD_ADJPOWER   "ADJPOWER"
#define	OSMO_TRXC_CMD_NOMTXPOWER   "NOMTXPOWER"
#define	OSMO_TRXC_CMD_SETRXGAIN   "SETRXGAIN"
#define	OSMO_TRXC_CMD_SETMAXDLY   "SETMAXDLY"
#define	OSMO_TRXC_CMD_SETMAXDLYNB   "SETMAXDLYNB"
#define	OSMO_TRXC_CMD_SETFORMAT   "SETFORMAT"
#define	OSMO_TRXC_CMD_HANDOVER   "HANDOVER"
#define	OSMO_TRXC_CMD_NOHANDOVER   "NOHANDOVER"
#define	OSMO_TRXC_CMD_RFMUTE   "RFMUTE"
#define	OSMO_TRXC_CMD_NOISELEV   "NOISELEV"
#define	OSMO_TRXC_CMD_SETFH   "SETFH"
#define	OSMO_TRXC_CMD_ERR   "ERR"
	verb of a reject response More...
#define	OSMO_TRXC_SETSLOT_TSC_MAX   3
	up to 3 sub-channels (VAMOS "HVHH") More...

Enumerations
enum	osmo_trxc_msg_type {   OSMO_TRXC_MT_CMD ,   OSMO_TRXC_MT_RSP ,   OSMO_TRXC_MT_IND }
enum	osmo_trxc_chan_comb {   OSMO_TRXC_CHAN_COMB_UNUSED = 0 ,   OSMO_TRXC_CHAN_COMB_TCHF = 1 ,   OSMO_TRXC_CHAN_COMB_TCHH_IDLE = 2 ,   OSMO_TRXC_CHAN_COMB_TCHH = 3 ,   OSMO_TRXC_CHAN_COMB_BCCH = 4 ,   OSMO_TRXC_CHAN_COMB_BCCH_SDCCH4 = 5 ,   OSMO_TRXC_CHAN_COMB_CCCH = 6 ,   OSMO_TRXC_CHAN_COMB_SDCCH8 = 7 ,   OSMO_TRXC_CHAN_COMB_TCHF_FACCH_SACCHM = 8 ,   OSMO_TRXC_CHAN_COMB_TCHF_SACCHM = 9 ,   OSMO_TRXC_CHAN_COMB_TCHFD_SACCHMD = 10 ,   OSMO_TRXC_CHAN_COMB_PBCCH = 11 ,   OSMO_TRXC_CHAN_COMB_PCCCH = 12 ,   OSMO_TRXC_CHAN_COMB_PDTCH = 13 }
	Classic (non-VAMOS) GSM TS 05.02 channel combinations, as used by the chan_comb parameter of SETSLOT. More...
enum	osmo_trxc_vamos_comb {   OSMO_TRXC_VAMOS_COMB_VFF = 1 ,   OSMO_TRXC_VAMOS_COMB_VHH ,   OSMO_TRXC_VAMOS_COMB_VFH ,   OSMO_TRXC_VAMOS_COMB_HVHH }
	VAMOS-enabled channel combinations: the chan_comb parameter of SETSLOT is symbolic (not numeric) for these. More...

Functions
int	osmo_trxc_msg_parse (struct osmo_trxc_msg *msg, const char *buf, size_t len)
	Parse a TRXC message ("CMD <verb> [<params>]", "RSP <verb> <status> [<params>]" or "IND <verb> <params>") from a zero-terminated buffer. More...
int	osmo_trxc_msg_build (char *buf, size_t buf_size, const struct osmo_trxc_msg *msg)
	Serialize a TRXC message into the given buffer (zero-terminated). More...
int	osmo_trxc_msg_params_scan (const struct osmo_trxc_msg *msg, const char *fmt,...)
	Parse the parameters string of a TRXC message, sscanf() style. More...
const char *	osmo_trxc_msg_name (const struct osmo_trxc_msg *msg)
	Compose a human-readable representation of the given message (for logging), store into a thread-local static buffer. More...
char *	osmo_trxc_msg_name_buf (char *buf, size_t buf_size, const struct osmo_trxc_msg *msg)
	Compose a human-readable representation of the given message (for logging), store into the given buffer. More...
static const char *	osmo_trxc_chan_comb_name (enum osmo_trxc_chan_comb comb)
static const char *	osmo_trxc_vamos_comb_name (enum osmo_trxc_vamos_comb comb)
int	osmo_trxc_setslot_parse (struct osmo_trxc_setslot *ss, const struct osmo_trxc_msg *msg)
	Parse SETSLOT parameters ("<tn> <chan_comb> [C<tsc>/S<tsc_set> ...]") from an already-parsed TRXC message's msg->params. More...
int	osmo_trxc_setslot_build (char *buf, size_t buf_size, const struct osmo_trxc_setslot *ss)
	Serialize SETSLOT parameters ("<tn> <chan_comb> [C<tsc>/S<tsc_set> ...]") into the given buffer (zero-terminated), for use as msg->params. More...
int	osmo_trxc_clock_ind_parse (uint32_t *fn, const char *buf, size_t len)
	Parse a clock indication ("IND CLOCK <fn>"). More...
int	osmo_trxc_clock_ind_build (char *buf, size_t buf_size, uint32_t fn)
	Serialize a clock indication ("IND CLOCK <fn>") into the given buffer. More...

Variables
const struct value_string	osmo_trxc_chan_comb_names []
const struct value_string	osmo_trxc_vamos_comb_names []

Detailed Description

TRXC (control) protocol and clock indications: I/O-free message codec.

Macro Definition Documentation

OSMO_TRXC_CMD_ADJPOWER

#define OSMO_TRXC_CMD_ADJPOWER   "ADJPOWER"

OSMO_TRXC_CMD_ERR

#define OSMO_TRXC_CMD_ERR   "ERR"

verb of a reject response

OSMO_TRXC_CMD_HANDOVER

#define OSMO_TRXC_CMD_HANDOVER   "HANDOVER"

OSMO_TRXC_CMD_LEN_MAX

#define OSMO_TRXC_CMD_LEN_MAX   32

Maximum length of a command verb (incl.

'\0')

OSMO_TRXC_CMD_NOHANDOVER

#define OSMO_TRXC_CMD_NOHANDOVER   "NOHANDOVER"

OSMO_TRXC_CMD_NOISELEV

#define OSMO_TRXC_CMD_NOISELEV   "NOISELEV"

OSMO_TRXC_CMD_NOMTXPOWER

#define OSMO_TRXC_CMD_NOMTXPOWER   "NOMTXPOWER"

OSMO_TRXC_CMD_POWEROFF

#define OSMO_TRXC_CMD_POWEROFF   "POWEROFF"

OSMO_TRXC_CMD_POWERON

#define OSMO_TRXC_CMD_POWERON   "POWERON"

OSMO_TRXC_CMD_RFMUTE

#define OSMO_TRXC_CMD_RFMUTE   "RFMUTE"

OSMO_TRXC_CMD_RXTUNE

#define OSMO_TRXC_CMD_RXTUNE   "RXTUNE"

OSMO_TRXC_CMD_SETBSIC

#define OSMO_TRXC_CMD_SETBSIC   "SETBSIC"

OSMO_TRXC_CMD_SETFH

#define OSMO_TRXC_CMD_SETFH   "SETFH"

OSMO_TRXC_CMD_SETFORMAT

#define OSMO_TRXC_CMD_SETFORMAT   "SETFORMAT"

OSMO_TRXC_CMD_SETMAXDLY

#define OSMO_TRXC_CMD_SETMAXDLY   "SETMAXDLY"

OSMO_TRXC_CMD_SETMAXDLYNB

#define OSMO_TRXC_CMD_SETMAXDLYNB   "SETMAXDLYNB"

OSMO_TRXC_CMD_SETPOWER

#define OSMO_TRXC_CMD_SETPOWER   "SETPOWER"

OSMO_TRXC_CMD_SETRXGAIN

#define OSMO_TRXC_CMD_SETRXGAIN   "SETRXGAIN"

OSMO_TRXC_CMD_SETSLOT

#define OSMO_TRXC_CMD_SETSLOT   "SETSLOT"

OSMO_TRXC_CMD_SETTSC

#define OSMO_TRXC_CMD_SETTSC   "SETTSC"

OSMO_TRXC_CMD_TXTUNE

#define OSMO_TRXC_CMD_TXTUNE   "TXTUNE"

OSMO_TRXC_MSG_BUF_SIZE

#define OSMO_TRXC_MSG_BUF_SIZE   1500

Recommended TRXC socket read/send buffer size.

OSMO_TRXC_PARAMS_LEN_MAX

#define OSMO_TRXC_PARAMS_LEN_MAX   (OSMO_TRXC_MSG_BUF_SIZE - OSMO_TRXC_CMD_LEN_MAX - 32)

Maximum length of the parameters string (incl.

'\0'). Must be large enough for SETFH, which carries the whole Mobile Allocation as pairs of Rx/Tx frequencies in kHz (over 1000 characters for 64 ARFCNs). Sized so that any message ("RSP " + verb + status) still fits the buffer above; the extra -32 is a rounded-up safety margin for that fixed overhead.

OSMO_TRXC_SETSLOT_TSC_MAX

#define OSMO_TRXC_SETSLOT_TSC_MAX   3

up to 3 sub-channels (VAMOS "HVHH")

Enumeration Type Documentation

osmo_trxc_chan_comb

enum osmo_trxc_chan_comb

Classic (non-VAMOS) GSM TS 05.02 channel combinations, as used by the chan_comb parameter of SETSLOT.

Numeric values match the wire format.

Enumerator
OSMO_TRXC_CHAN_COMB_UNUSED	Channel is transmitted, but unused.
OSMO_TRXC_CHAN_COMB_TCHF
OSMO_TRXC_CHAN_COMB_TCHH_IDLE	TCH/HS, idle every other slot.
OSMO_TRXC_CHAN_COMB_TCHH
OSMO_TRXC_CHAN_COMB_BCCH	DL: FCCH+SCH+CCCH+BCCH, UL: RACH.
OSMO_TRXC_CHAN_COMB_BCCH_SDCCH4	DL: +SDCCH/4+SACCH/4, UL: +SDCCH/4.
OSMO_TRXC_CHAN_COMB_CCCH	DL: CCCH+BCCH, UL: RACH.
OSMO_TRXC_CHAN_COMB_SDCCH8	SDCCH/8 + SACCH/8.
OSMO_TRXC_CHAN_COMB_TCHF_FACCH_SACCHM
OSMO_TRXC_CHAN_COMB_TCHF_SACCHM
OSMO_TRXC_CHAN_COMB_TCHFD_SACCHMD
OSMO_TRXC_CHAN_COMB_PBCCH	PBCCH+PCCCH+PDTCH+PACCH+PTCCH.
OSMO_TRXC_CHAN_COMB_PCCCH	PCCCH+PDTCH+PACCH+PTCCH.
OSMO_TRXC_CHAN_COMB_PDTCH	PDTCH+PACCH+PTCCH.

osmo_trxc_msg_type

enum osmo_trxc_msg_type

Enumerator
OSMO_TRXC_MT_CMD	"CMD <verb> [<params>]" (L1 -> TRX)
OSMO_TRXC_MT_RSP	"RSP <verb> <status> [<params>]" (TRX -> L1)
OSMO_TRXC_MT_IND	"IND <verb> <params>" (TRX -> L1)

osmo_trxc_vamos_comb

enum osmo_trxc_vamos_comb

VAMOS-enabled channel combinations: the chan_comb parameter of SETSLOT is symbolic (not numeric) for these.

Enumerator
OSMO_TRXC_VAMOS_COMB_VFF	V0(TCH/F) & V1(TCH/F)
OSMO_TRXC_VAMOS_COMB_VHH	V0(TCH/H0)&V1(TCH/H0) + V0(TCH/H1)&V1(TCH/H1)
OSMO_TRXC_VAMOS_COMB_VFH	V0(TCH/F) & V1(TCH/H0) + V0(TCH/F) & V1(TCH/H1)
OSMO_TRXC_VAMOS_COMB_HVHH	TCH/H0 + V0(TCH/H1) & V1(TCH/H1) (mixed)

Function Documentation

osmo_trxc_chan_comb_name()

static const char * osmo_trxc_chan_comb_name ( enum osmo_trxc_chan_comb  comb )

inlinestatic

References osmo_trxc_chan_comb_names.

osmo_trxc_clock_ind_build()

int osmo_trxc_clock_ind_build	(	char *	buf,
		size_t	buf_size,
		uint32_t	fn
	)

Serialize a clock indication ("IND CLOCK <fn>") into the given buffer.

Parameters

[out]	buf	message buffer to store the result
[in]	buf_size	size of the message buffer
[in]	fn	TDMA frame number (validated to be < GSM_TDMA_HYPERFRAME)

Returns

length of the message (excl. '\0') on success; negative on error

Referenced by osmo_trx_ep_send_clck_ind().

osmo_trxc_clock_ind_parse()

int osmo_trxc_clock_ind_parse	(	uint32_t *	fn,
		const char *	buf,
		size_t	len
	)

Parse a clock indication ("IND CLOCK <fn>").

Parameters

[out]	fn	TDMA frame number (validated to be < GSM_TDMA_HYPERFRAME)
[in]	buf	message buffer (not necessarily zero-terminated)
[in]	len	length of the message in the buffer

Returns

0 on success; negative on error

References osmo_trxc_msg::cmd, osmo_trxc_msg_params_scan(), osmo_trxc_msg_parse(), OSMO_TRXC_MT_IND, and osmo_trxc_msg::type.

Referenced by trx_ep_clck_read_cb().

osmo_trxc_msg_build()

int osmo_trxc_msg_build	(	char *	buf,
		size_t	buf_size,
		const struct osmo_trxc_msg *	msg
	)

Serialize a TRXC message into the given buffer (zero-terminated).

Returns

length of the message (excl. '\0') on success; negative on error

References osmo_trxc_msg::cmd, OSMO_TRXC_MT_CMD, OSMO_TRXC_MT_IND, OSMO_TRXC_MT_RSP, osmo_trxc_msg::params, osmo_trxc_msg::status, trxc_msg_type_names, and osmo_trxc_msg::type.

Referenced by osmo_trx_ep_send_ctrl_msg(), and osmo_trxc_msg_name_buf().

osmo_trxc_msg_name()

const char * osmo_trxc_msg_name

(

const struct osmo_trxc_msg *

msg

)

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

Parameters

[in]

msg

parsed TRXC message to get a human-readable representation of

Returns

pointer to a thread-local static buffer; NULL on error

References OSMO_TRXC_MSG_BUF_SIZE, and osmo_trxc_msg_name_buf().

Referenced by osmo_trxc_client_rx_msg(), trxc_client_default_rsp_cb(), trxc_client_fatal(), and trxc_client_send_next().

osmo_trxc_msg_name_buf()

char * osmo_trxc_msg_name_buf	(	char *	buf,
		size_t	buf_size,
		const struct osmo_trxc_msg *	msg
	)

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

Parameters

[out]	buf	output buffer to store the result
[in]	buf_size	size of the output buffer
[in]	msg	parsed TRXC message to get a human-readable representation of

Returns

pointer to the given buffer; NULL on error

References osmo_trxc_msg_build().

Referenced by osmo_trxc_msg_name().

osmo_trxc_msg_params_scan()

int osmo_trxc_msg_params_scan	(	const struct osmo_trxc_msg *	msg,
		const char *	fmt,
			...
	)

Parse the parameters string of a TRXC message, sscanf() style.

Returns

number of successfully matched items (see sscanf)

References osmo_trxc_msg::params.

Referenced by osmo_trxc_clock_ind_parse().

osmo_trxc_msg_parse()

int osmo_trxc_msg_parse	(	struct osmo_trxc_msg *	msg,
		const char *	buf,
		size_t	len
	)

Parse a TRXC message ("CMD <verb> [<params>]", "RSP <verb> <status> [<params>]" or "IND <verb> <params>") from a zero-terminated buffer.

Parameters

[out]	msg	parsed message
[in]	buf	message buffer (not necessarily zero-terminated)
[in]	len	length of the message in the buffer

Returns

0 on success; negative on error

References osmo_trxc_msg::cmd, OSMO_TRXC_MSG_BUF_SIZE, OSMO_TRXC_MT_CMD, OSMO_TRXC_MT_IND, OSMO_TRXC_MT_RSP, osmo_trxc_msg::params, osmo_trxc_msg::status, and osmo_trxc_msg::type.

Referenced by osmo_trxc_client_rx(), osmo_trxc_clock_ind_parse(), and trx_ep_ctrl_recvfrom_cb().

osmo_trxc_setslot_build()

int osmo_trxc_setslot_build	(	char *	buf,
		size_t	buf_size,
		const struct osmo_trxc_setslot *	ss
	)

Serialize SETSLOT parameters ("<tn> <chan_comb> [C<tsc>/S<tsc_set> ...]") into the given buffer (zero-terminated), for use as msg->params.

Returns

length of the string (excl. '\0') on success; negative on error

References osmo_trxc_setslot::chan_comb, osmo_trxc_setslot::num_tsc, osmo_trxc_vamos_comb_name(), osmo_trxc_setslot::tn, osmo_trxc_setslot_tsc::tsc, osmo_trxc_setslot::tsc, osmo_trxc_setslot_tsc::tsc_set, osmo_trxc_setslot::vamos, and osmo_trxc_setslot::vamos_comb.

osmo_trxc_setslot_parse()

int osmo_trxc_setslot_parse	(	struct osmo_trxc_setslot *	ss,
		const struct osmo_trxc_msg *	msg
	)

Parse SETSLOT parameters ("<tn> <chan_comb> [C<tsc>/S<tsc_set> ...]") from an already-parsed TRXC message's msg->params.

Returns

0 on success; negative on error

References osmo_trxc_setslot::chan_comb, osmo_trxc_setslot::num_tsc, OSMO_TRXC_CHAN_COMB_PDTCH, OSMO_TRXC_PARAMS_LEN_MAX, OSMO_TRXC_SETSLOT_TSC_MAX, osmo_trxc_vamos_comb_names, osmo_trxc_msg::params, osmo_trxc_setslot::tn, osmo_trxc_setslot_tsc::tsc, osmo_trxc_setslot::tsc, osmo_trxc_setslot_tsc::tsc_set, osmo_trxc_setslot::vamos, and osmo_trxc_setslot::vamos_comb.

osmo_trxc_vamos_comb_name()

static const char * osmo_trxc_vamos_comb_name ( enum osmo_trxc_vamos_comb  comb )

inlinestatic

References osmo_trxc_vamos_comb_names.

Referenced by osmo_trxc_setslot_build().

Variable Documentation

osmo_trxc_chan_comb_names

const struct value_string osmo_trxc_chan_comb_names[]

extern

Referenced by osmo_trxc_chan_comb_name().

osmo_trxc_vamos_comb_names

const struct value_string osmo_trxc_vamos_comb_names[]

extern

Referenced by osmo_trxc_setslot_parse(), and osmo_trxc_vamos_comb_name().