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

#include <errno.h>
#include <stdio.h>
#include <string.h>
#include <stdarg.h>
#include <stdbool.h>
#include <osmocom/core/talloc.h>
#include <osmocom/core/timer.h>
#include <osmocom/core/logging.h>
#include <osmocom/core/linuxlist.h>
#include <osmocom/core/utils.h>
#include <osmocom/trx/trxc.h>
#include <osmocom/trx/trxc_client.h>

Data Structures
struct	trxc_cmd_entry
	A single command in the queue. More...

struct	osmo_trxc_client

struct	trxc_setformat_ctx
	Per-call SETFORMAT negotiation state, passed as cb_data through osmo_trxc_client_send_cmd() and freed in setformat_rsp_cb() More...

Macros
#define	TRXC_CLIENT_RETRANS_SEC 2
	Default retransmit timeout (in seconds) More...

#define	LOGCL(client, level, fmt, args...) LOGP((client)->log_cat, level, "%s: " fmt, (client)->name, ## args)

#define	CMD_NAME_FMT "CMD %s%s%s"

#define	CMD_NAME_ARGS(e) (e)->msg.cmd, (e)->msg.params[0] != '\0' ? " " : "", (e)->msg.params

Functions
static int	trxc_client_fatal (struct osmo_trxc_client client, const struct osmo_trxc_msg rsp)

static void	trxc_client_send_next (struct osmo_trxc_client *client)

static void	trxc_client_retrans_timer_cb (void *data)

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

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_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...

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

static bool	cmd_matches_rsp (const struct trxc_cmd_entry e, const struct osmo_trxc_msg rsp)

static int	trxc_client_default_rsp_cb (struct osmo_trxc_client client, const struct trxc_cmd_entry e, const struct osmo_trxc_msg *rsp)

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

static int	setformat_rsp_cb (struct osmo_trxc_client client, const struct osmo_trxc_msg rsp, void *cb_data)

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

Detailed Description

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

Based on the TRXC command queue logic in osmo-bts-trx (trx_if.c).

Macro Definition Documentation

◆ CMD_NAME_ARGS

#define CMD_NAME_ARGS ( e ) (e)->msg.cmd, (e)->msg.params[0] != '\0' ? " " : "", (e)->msg.params

◆ CMD_NAME_FMT

#define CMD_NAME_FMT "CMD %s%s%s"

◆ LOGCL

#define LOGCL	(	client,
		level,
		fmt,
		args...
	)	LOGP((client)->log_cat, level, "%s: " fmt, (client)->name, ## args)

◆ TRXC_CLIENT_RETRANS_SEC

#define TRXC_CLIENT_RETRANS_SEC 2

Default retransmit timeout (in seconds)

Function Documentation

◆ cmd_matches_rsp()

static bool cmd_matches_rsp	(	const struct trxc_cmd_entry *	e,
		const struct osmo_trxc_msg *	rsp
	)

static

References osmo_trxc_msg::cmd, trxc_cmd_entry::flags, trxc_cmd_entry::msg, OSMO_TRXC_F_MATCH_PARAMS, and osmo_trxc_msg::params.

Referenced by osmo_trxc_client_rx_msg().

◆ 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_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_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)

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.