TRXC client command queue engine: queue, retransmission, RSP matching. More...

#include <stdint.h>
#include <stddef.h>
#include <osmocom/trx/trxc.h>

Macros
#define	OSMO_TRXC_F_CRITICAL (1 << 0)
	escalate to the fatal_error call-back on NACK More...

#define	OSMO_TRXC_F_MATCH_PARAMS (1 << 1)
	RSP params must echo CMD params (e.g. More...

Typedefs
typedef int	osmo_trxc_client_rsp_cb(struct osmo_trxc_client client, const struct osmo_trxc_msg rsp, void *cb_data)
	Response call-back, invoked when a response to a command is received. More...

typedef int	osmo_trxc_client_tx_msg_cb(struct osmo_trxc_client client, const struct osmo_trxc_msg msg)
	Transmit call-back, invoked to emit a parsed TRXC message (mandatory, see osmo_trxc_client_set_tx_msg_cb()). More...

typedef void	osmo_trxc_client_fatal_error_cb(struct osmo_trxc_client client, const struct osmo_trxc_msg rsp)
	Fatal error call-back, invoked when a critical command definitively fails (optional; default: log), see osmo_trxc_client_set_fatal_error_cb(). More...

typedef void	osmo_trxc_setformat_cb(struct osmo_trxc_client client, uint8_t ver_use, void cb_data)
	TRXD PDU version negotiation result call-back. More...

Functions
struct osmo_trxc_client *	osmo_trxc_client_alloc (void *ctx)
	Allocate a TRXC client instance. More...

void	osmo_trxc_client_free (struct osmo_trxc_client *client)
	Free the given TRXC client instance (flushes the command queue). More...

void	osmo_trxc_client_set_priv (struct osmo_trxc_client client, void priv)
	Set the application-private data. More...

void *	osmo_trxc_client_get_priv (const struct osmo_trxc_client *client)
	Obtain the application-private data. More...

int	osmo_trxc_client_set_name (struct osmo_trxc_client client, const char fmt,...)
	Set the name (log prefix) of the given instance, e.g. More...

void	osmo_trxc_client_set_log_cat (struct osmo_trxc_client *client, int log_cat)
	Set the logging category (e.g. More...

int	osmo_trxc_client_set_retrans (struct osmo_trxc_client *client, unsigned int sec)
	Set the retransmit timeout in seconds (default: 2). More...

void	osmo_trxc_client_set_max_retrans (struct osmo_trxc_client *client, unsigned int n)
	Set the maximum number of retransmissions of a command (default: 0). More...

void	osmo_trxc_client_set_tx_msg_cb (struct osmo_trxc_client client, osmo_trxc_client_tx_msg_cb cb)
	set the tx_msg call-back (mandatory before the first command is sent) More...

void	osmo_trxc_client_set_fatal_error_cb (struct osmo_trxc_client client, osmo_trxc_client_fatal_error_cb cb)
	set the fatal_error call-back (optional; default: log) More...

int	osmo_trxc_client_send_cmd (struct osmo_trxc_client client, uint32_t flags, osmo_trxc_client_rsp_cb cb, void cb_data, const char cmd, const char *fmt,...)
	Enqueue a new command for transmission. More...

void	osmo_trxc_client_flush (struct osmo_trxc_client *client)
	Flush (drop) all pending commands. More...

int	osmo_trxc_client_rx_msg (struct osmo_trxc_client client, const struct osmo_trxc_msg rsp)
	Feed a received (parsed) response message into the engine. More...

int	osmo_trxc_client_rx (struct osmo_trxc_client client, const char buf, size_t len)
	Feed a datagram received on the ctrl socket into the engine. More...

int	osmo_trxc_client_negotiate_format (struct osmo_trxc_client client, uint8_t ver_max, osmo_trxc_setformat_cb cb, void *cb_data)
	Negotiate the TRXD PDU version with the transceiver (SETFORMAT). More...

static int	osmo_trxc_client_poweron (struct osmo_trxc_client client, osmo_trxc_client_rsp_cb cb, void *cb_data)

static int	osmo_trxc_client_poweroff (struct osmo_trxc_client client, osmo_trxc_client_rsp_cb cb, void *cb_data)

static int	osmo_trxc_client_rxtune (struct osmo_trxc_client client, unsigned int freq_khz, osmo_trxc_client_rsp_cb cb, void *cb_data)

static int	osmo_trxc_client_txtune (struct osmo_trxc_client client, unsigned int freq_khz, osmo_trxc_client_rsp_cb cb, void *cb_data)

Detailed Description

TRXC client command queue engine: queue, retransmission, RSP matching.

Macro Definition Documentation

◆ OSMO_TRXC_F_CRITICAL

#define OSMO_TRXC_F_CRITICAL (1 << 0)

escalate to the fatal_error call-back on NACK

◆ OSMO_TRXC_F_MATCH_PARAMS

#define OSMO_TRXC_F_MATCH_PARAMS (1 << 1)

RSP params must echo CMD params (e.g.

SETSLOT, SETFORMAT)

Typedef Documentation

◆ osmo_trxc_client_fatal_error_cb

typedef void osmo_trxc_client_fatal_error_cb(struct osmo_trxc_client *client, const struct osmo_trxc_msg *rsp)

Fatal error call-back, invoked when a critical command definitively fails (optional; default: log), see osmo_trxc_client_set_fatal_error_cb().

The command queue remains frozen after this call.

Parameters

[in]	client	TRXC client instance
[in]	rsp	the offending response (NULL on a retransmission timeout, i.e. no response was ever received)

◆ osmo_trxc_client_rsp_cb

typedef int osmo_trxc_client_rsp_cb(struct osmo_trxc_client *client, const struct osmo_trxc_msg *rsp, void *cb_data)

Response call-back, invoked when a response to a command is received.

Parameters

[in]	client	TRXC client instance
[in]	rsp	received response message
[in]	cb_data	opaque data passed to osmo_trxc_client_send_cmd()

Returns: 0 when done (the command gets dequeued); N > 0 to re-send the same command after N seconds; negative to indicate a fatal error (like a NACKed critical command, ends up in the fatal_error call-back)

◆ osmo_trxc_client_tx_msg_cb

typedef int osmo_trxc_client_tx_msg_cb(struct osmo_trxc_client *client, const struct osmo_trxc_msg *msg)

Transmit call-back, invoked to emit a parsed TRXC message (mandatory, see osmo_trxc_client_set_tx_msg_cb()).

E.g. osmo_trx_ep_send_ctrl_msg() for osmo_trx_ep users, or osmo_trxc_msg_build() + write() on a self-managed ctrl socket.

Parameters

[in]	client	TRXC client instance
[in]	msg	TRXC message to transmit

Returns: 0 on success; negative on error (logged by the engine, otherwise ignored: the retransmit timer still governs delivery)

◆ osmo_trxc_setformat_cb

typedef void osmo_trxc_setformat_cb(struct osmo_trxc_client *client, uint8_t ver_use, void *cb_data)

TRXD PDU version negotiation result call-back.

Parameters

[in]	client	TRXC client instance
[in]	ver_use	the negotiated version to be used
[in]	cb_data	data that was passed to osmo_trxc_client_negotiate_format()

Function Documentation

◆ osmo_trxc_client_alloc()

struct osmo_trxc_client * osmo_trxc_client_alloc ( void * ctx )

Allocate a TRXC client instance.

The tx_msg call-back must be set via osmo_trxc_client_set_tx_msg_cb() before the first command is sent.

Parameters

[in] ctx talloc context to allocate from

Returns: pointer to the allocated instance; NULL on error

References osmo_trxc_client::cmd_queue, osmo_trxc_client::log_cat, osmo_trxc_client::name, osmo_trxc_client::retrans_sec, osmo_trxc_client::retrans_timer, TRXC_CLIENT_RETRANS_SEC, and trxc_client_retrans_timer_cb().

◆ osmo_trxc_client_flush()

void osmo_trxc_client_flush ( struct osmo_trxc_client * client )

Flush (drop) all pending commands.

May be called from within a response call-back.

References osmo_trxc_client::cmd_queue, osmo_trxc_client::flushed_in_rx, osmo_trxc_client::in_rx, osmo_trxc_client::last_acked, trxc_cmd_entry::list, and osmo_trxc_client::retrans_timer.

Referenced by osmo_trxc_client_free().

◆ osmo_trxc_client_free()

void osmo_trxc_client_free ( struct osmo_trxc_client * client )

Free the given TRXC client instance (flushes the command queue).

Must not be called from within a response call-back.

References osmo_trxc_client::in_rx, and osmo_trxc_client_flush().

◆ osmo_trxc_client_get_priv()

void * osmo_trxc_client_get_priv ( const struct osmo_trxc_client * client )

Obtain the application-private data.

References osmo_trxc_client::priv.

◆ osmo_trxc_client_negotiate_format()

int osmo_trxc_client_negotiate_format	(	struct osmo_trxc_client *	client,
		uint8_t	ver_max,
		osmo_trxc_setformat_cb *	cb,
		void *	cb_data
	)

Negotiate the TRXD PDU version with the transceiver (SETFORMAT).

If the transceiver does not support the format negotiation at all, it rejects the command with 'RSP ERR 1' and version 0 is assumed. If the requested version is not supported by the transceiver, the status code of the response indicates a preferred lower version.

Parameters

[in]	client	TRXC client instance
[in]	ver_max	the maximum (desired) TRXD PDU version
[in]	cb	call-back invoked with the negotiated version
[in]	cb_data	opaque data for the call-back

Returns: 0 on success; negative on error

References trxc_setformat_ctx::cb, trxc_setformat_ctx::cb_data, LOGCL, osmo_trxc_client_send_cmd(), OSMO_TRXC_CMD_SETFORMAT, OSMO_TRXC_F_MATCH_PARAMS, setformat_rsp_cb(), and trxc_setformat_ctx::ver_req.

◆ osmo_trxc_client_poweroff()

static int osmo_trxc_client_poweroff	(	struct osmo_trxc_client *	client,
		osmo_trxc_client_rsp_cb *	cb,
		void *	cb_data
	)

inlinestatic

References osmo_trxc_client_send_cmd(), OSMO_TRXC_CMD_POWEROFF, and OSMO_TRXC_F_CRITICAL.

◆ osmo_trxc_client_poweron()

static int osmo_trxc_client_poweron	(	struct osmo_trxc_client *	client,
		osmo_trxc_client_rsp_cb *	cb,
		void *	cb_data
	)

inlinestatic

References osmo_trxc_client_send_cmd(), OSMO_TRXC_CMD_POWERON, and OSMO_TRXC_F_CRITICAL.

◆ osmo_trxc_client_rx()

int osmo_trxc_client_rx	(	struct osmo_trxc_client *	client,
		const char *	buf,
		size_t	len
	)

Feed a datagram received on the ctrl socket into the engine.

A convenience wrapper around osmo_trxc_client_rx_msg() for applications managing the TRXC socket themselves: parses the given datagram first.

Parameters

[in]	client	TRXC client instance
[in]	buf	received datagram (not necessarily zero-terminated)
[in]	len	length of the datagram

Returns: 0 on success; negative on error

References LOGCL, osmo_trxc_client_rx_msg(), and osmo_trxc_msg_parse().

◆ osmo_trxc_client_rx_msg()

int osmo_trxc_client_rx_msg	(	struct osmo_trxc_client *	client,
		const struct osmo_trxc_msg *	rsp
	)

Feed a received (parsed) response message into the engine.

The engine filters duplicate responses caused by retransmissions, matches the response against the command in flight, invokes its response call-back and transmits the next queued command (if any). E.g. an osmo_trx_ep user calls this from osmo_trx_ep_rx_ctrl_msg().

Parameters

[in]	client	TRXC client instance
[in]	rsp	received message (rsp->type must be OSMO_TRXC_MT_RSP)

Returns: 0 on success; negative on error

References trxc_cmd_entry::cb_data, cmd_matches_rsp(), CMD_NAME_ARGS, CMD_NAME_FMT, osmo_trxc_client::cmd_queue, trxc_cmd_entry::flags, osmo_trxc_client::flushed_in_rx, osmo_trxc_client::in_rx, osmo_trxc_client::last_acked, trxc_cmd_entry::list, LOGCL, trxc_cmd_entry::n_retrans, OSMO_TRXC_F_CRITICAL, osmo_trxc_msg_name(), OSMO_TRXC_MT_RSP, osmo_trxc_client::retrans_sec, osmo_trxc_client::retrans_timer, trxc_cmd_entry::rsp_cb, trxc_client_default_rsp_cb(), trxc_client_fatal(), trxc_client_send_next(), and osmo_trxc_msg::type.

Referenced by osmo_trxc_client_rx().

◆ osmo_trxc_client_rxtune()

static int osmo_trxc_client_rxtune	(	struct osmo_trxc_client *	client,
		unsigned int	freq_khz,
		osmo_trxc_client_rsp_cb *	cb,
		void *	cb_data
	)

inlinestatic

References osmo_trxc_client_send_cmd(), OSMO_TRXC_CMD_RXTUNE, and OSMO_TRXC_F_CRITICAL.

◆ osmo_trxc_client_send_cmd()

int osmo_trxc_client_send_cmd	(	struct osmo_trxc_client *	client,
		uint32_t	flags,
		osmo_trxc_client_rsp_cb *	cb,
		void *	cb_data,
		const char *	cmd,
		const char *	fmt,
			...
	)

Enqueue a new command for transmission.

The new command is added to the end of the queue; there's at most one command in flight at any time. Consecutive duplicate commands are not enqueued. Commands are retransmitted until a matching response is received (see osmo_trxc_client_rx()).

Parameters

[in]	client	TRXC client instance
[in]	flags	OSMO_TRXC_F_*
[in]	cb	call-back invoked on the response (optional); without it, a NACKed OSMO_TRXC_F_CRITICAL command is escalated to the fatal_error call-back, other responses are just logged
[in]	cb_data	opaque data for the response call-back
[in]	cmd	command verb, e.g. "POWERON"
[in]	fmt	format string for the parameters (optional, may be NULL)

Returns: 0 on success; negative on error

References trxc_cmd_entry::cb_data, osmo_trxc_msg::cmd, CMD_NAME_ARGS, CMD_NAME_FMT, osmo_trxc_client::cmd_queue, trxc_cmd_entry::flags, osmo_trxc_client::in_rx, trxc_cmd_entry::list, LOGCL, trxc_cmd_entry::msg, OSMO_TRXC_MT_CMD, osmo_trxc_msg::params, trxc_cmd_entry::rsp_cb, trxc_client_send_next(), and osmo_trxc_msg::type.

Referenced by osmo_trxc_client_negotiate_format(), osmo_trxc_client_poweroff(), osmo_trxc_client_poweron(), osmo_trxc_client_rxtune(), and osmo_trxc_client_txtune().

◆ osmo_trxc_client_set_fatal_error_cb()

void osmo_trxc_client_set_fatal_error_cb	(	struct osmo_trxc_client *	client,
		osmo_trxc_client_fatal_error_cb *	cb
	)

set the fatal_error call-back (optional; default: log)

References osmo_trxc_client::fatal_error_cb.

◆ osmo_trxc_client_set_log_cat()

void osmo_trxc_client_set_log_cat	(	struct osmo_trxc_client *	client,
		int	log_cat
	)

Set the logging category (e.g.

DTRX in osmo-bts; default: DLGLOBAL)

References osmo_trxc_client::log_cat.

◆ osmo_trxc_client_set_max_retrans()

void osmo_trxc_client_set_max_retrans	(	struct osmo_trxc_client *	client,
		unsigned int	n
	)

Set the maximum number of retransmissions of a command (default: 0).

Once a command has been retransmitted the given number of times without a response, the engine gives up and escalates to the fatal_error call-back (with rsp == NULL); the command queue remains frozen. The special value 0 means no limit: retransmit indefinitely.

References osmo_trxc_client::max_retrans.

◆ osmo_trxc_client_set_name()

int osmo_trxc_client_set_name	(	struct osmo_trxc_client *	client,
		const char *	fmt,
			...
	)

Set the name (log prefix) of the given instance, e.g.

"phy0.trx0"

References osmo_trxc_client::name.

◆ osmo_trxc_client_set_priv()

void osmo_trxc_client_set_priv	(	struct osmo_trxc_client *	client,
		void *	priv
	)

Set the application-private data.

References osmo_trxc_client::priv.

◆ osmo_trxc_client_set_retrans()

int osmo_trxc_client_set_retrans	(	struct osmo_trxc_client *	client,
		unsigned int	sec
	)

Set the retransmit timeout in seconds (default: 2).

Parameters

[in]	client	TRXC client instance
[in]	sec	retransmit timeout; 0 is not allowed

Returns: 0 on success; -EINVAL if sec == 0

References osmo_trxc_client::retrans_sec.

◆ osmo_trxc_client_set_tx_msg_cb()

void osmo_trxc_client_set_tx_msg_cb	(	struct osmo_trxc_client *	client,
		osmo_trxc_client_tx_msg_cb *	cb
	)

set the tx_msg call-back (mandatory before the first command is sent)

References osmo_trxc_client::tx_msg_cb.

◆ osmo_trxc_client_txtune()

static int osmo_trxc_client_txtune	(	struct osmo_trxc_client *	client,
		unsigned int	freq_khz,
		osmo_trxc_client_rsp_cb *	cb,
		void *	cb_data
	)

inlinestatic

References osmo_trxc_client_send_cmd(), OSMO_TRXC_CMD_TXTUNE, and OSMO_TRXC_F_CRITICAL.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ OSMO_TRXC_F_CRITICAL

◆ OSMO_TRXC_F_MATCH_PARAMS

Typedef Documentation

◆ osmo_trxc_client_fatal_error_cb

◆ osmo_trxc_client_rsp_cb

◆ osmo_trxc_client_tx_msg_cb

◆ osmo_trxc_setformat_cb

Function Documentation

◆ osmo_trxc_client_alloc()

◆ osmo_trxc_client_flush()

◆ osmo_trxc_client_free()

◆ osmo_trxc_client_get_priv()

◆ osmo_trxc_client_negotiate_format()

◆ osmo_trxc_client_poweroff()

◆ osmo_trxc_client_poweron()

◆ osmo_trxc_client_rx()

◆ osmo_trxc_client_rx_msg()

◆ osmo_trxc_client_rxtune()

◆ osmo_trxc_client_send_cmd()

◆ osmo_trxc_client_set_fatal_error_cb()

◆ osmo_trxc_client_set_log_cat()

◆ osmo_trxc_client_set_max_retrans()

◆ osmo_trxc_client_set_name()

◆ osmo_trxc_client_set_priv()

◆ osmo_trxc_client_set_retrans()

◆ osmo_trxc_client_set_tx_msg_cb()

◆ osmo_trxc_client_txtune()