#include <osmocom/core/msgb.h>
#include <osmocom/core/talloc.h>
#include <osmocom/core/write_queue.h>
#include <osmocom/core/logging.h>
#include <osmocom/core/utils.h>
#include <osmocom/vty/vector.h>

Data Structures
struct	ctrl_connection
	Represents a single ctrl connection. More...

struct	ctrl_cmd
	Represents a single ctrl command after parsing. More...

struct	ctrl_cmd_struct

struct	ctrl_cmd_element
	Implementation of a given CTRL command. More...

struct	ctrl_cmd_map

struct	ctrl_cmd_def

Macros
#define	CTRL_CMD_ERROR -1

#define	CTRL_CMD_HANDLED 0

#define	CTRL_CMD_REPLY 1

#define	CTRL_CMD_TRAP_ID "0"

#define	ctrl_cmd_reply_printf(cmd, fmt, args...) osmo_talloc_asprintf(cmd, cmd->reply, fmt, ## args)

#define	CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_name)
	Helper to generate static struct ctrl_cmd_element. More...

#define	CTRL_HELPER_GET_INT(cmdname, dtype, element)
	Helper to generate static GET function for integer. More...

#define	CTRL_HELPER_SET_INT(cmdname, dtype, element)
	Helper to generate static SET function for integer. More...

#define	CTRL_HELPER_VERIFY_RANGE(cmdname, min, max)
	Helper to generate static VERIFY unction validating a numeric range. More...

#define	CTRL_CMD_DEFINE_RANGE(cmdname, cmdstr, dtype, element, min, max)
	Helper to generate GET, SET, VERIFY + ctrl_cmd_element for integer. More...

#define	CTRL_HELPER_GET_STRING(cmdname, dtype, element)
	Helper to generate static GET function for string. More...

#define	CTRL_HELPER_SET_STRING(cmdname, dtype, element)
	Helper to generate static SET function for string. More...

#define	CTRL_CMD_DEFINE_STRING(cmdname, cmdstr, dtype, element)
	Helper to generate GET, SET, VERIFY + ctrl_cmd_element for string. More...

#define	CTRL_CMD_DEFINE(cmdname, cmdstr)
	Declare a read-write attribute. More...

#define	CTRL_CMD_DEFINE_RO(cmdname, cmdstr)
	Define a read-only attribute. More...

#define	CTRL_CMD_DEFINE_WO(cmdname, cmdstr)
	Define a write-only attribute. More...

#define	CTRL_CMD_DEFINE_WO_NOVRF(cmdname, cmdstr)
	Define a write-only attribute without verify. More...

Enumerations
enum	ctrl_node_type { CTRL_NODE_ROOT, CTRL_NODE_BTS, CTRL_NODE_TRX, CTRL_NODE_TS, CTRL_NODE_FSM, CTRL_NODE_FSM_INST, _LAST_CTRL_NODE }
	The class of node at which a ctrl command is registered to. More...

enum	ctrl_type { CTRL_TYPE_UNKNOWN, CTRL_TYPE_GET, CTRL_TYPE_SET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET_REPLY, CTRL_TYPE_TRAP, CTRL_TYPE_ERROR }
	Ctrl command types (GET, SET, ...) More...

Functions
struct ctrl_cmd_def *	ctrl_cmd_def_make (const void ctx, struct ctrl_cmd cmd, void *data, unsigned int secs)
	Build a deferred control command state and keep it the per-connection list of deferred commands. More...

int	ctrl_cmd_def_is_zombie (struct ctrl_cmd_def *cd)
	Determine if the given deferred control command is still alive or a zombie. More...

int	ctrl_cmd_def_send (struct ctrl_cmd_def *cd)
	Send the response to a deferred ctrl command. More...

int	ctrl_cmd_exec (vector vline, struct ctrl_cmd command, vector node, void data)
	Execute a given received command. More...

int	ctrl_cmd_install (enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
	Install a given command definition at a given CTRL node. More...

int	ctrl_cmd_send (struct osmo_wqueue queue, struct ctrl_cmd cmd)
	Encode a CTRL command and append it to the given write queue. More...

int	ctrl_cmd_send_to_all (struct ctrl_handle ctrl, struct ctrl_cmd cmd)
	Send a CTRL command to all connections. More...

struct ctrl_cmd *	ctrl_cmd_parse3 (void ctx, struct msgb msg, bool *parse_failed)
	Parse/Decode CTRL from Message buffers into command struct. More...

struct ctrl_cmd *	ctrl_cmd_parse2 (void ctx, struct msgb msg)
	Parse/Decode CTRL from Message buffers into command struct. More...

struct ctrl_cmd *	ctrl_cmd_parse (void ctx, struct msgb msg)
	Parse/Decode CTRL from Message buffers into command struct. More...

struct msgb *	ctrl_cmd_make (struct ctrl_cmd *cmd)
	Encode a given CTRL command from its parsed form into a message buffer. More...

struct ctrl_cmd *	ctrl_cmd_cpy (void ctx, struct ctrl_cmd cmd)
	Perform a deepl copy of the given cmd, allocating memory from ctx. More...

struct ctrl_cmd *	ctrl_cmd_create (void *ctx, enum ctrl_type)
	Allocate a control command of given type. More...

struct ctrl_cmd *	ctrl_cmd_trap (struct ctrl_cmd *cmd)
	Copy given cmd and convert copy to CTRL_TYPE_TRAP. More...

Variables
const struct value_string	ctrl_type_vals []
	human-readable string names for ctrl_type More...

Macro Definition Documentation

#define CTRL_CMD_DEFINE	(	cmdname,
		cmdstr
	)

Value:

static int get_##cmdname(struct ctrl_cmd *cmd, void *data); \
static int set_##cmdname(struct ctrl_cmd *cmd, void *data); \
static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *data); \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)

Declare a read-write attribute.

Declares get, set, verify.

Parameters

[in]	cmdname	symbol name of the command related functions/structures
[in]	cmdstr	string name exposed on CTRL

#define CTRL_CMD_DEFINE_RANGE	(	cmdname,
		cmdstr,
		dtype,
		element,
		min,
		max
	)

Value:

CTRL_HELPER_GET_INT(cmdname, dtype, element) \
	CTRL_HELPER_SET_INT(cmdname, dtype, element) \
	CTRL_HELPER_VERIFY_RANGE(cmdname, min, max) \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)

Helper to generate GET, SET, VERIFY + ctrl_cmd_element for integer.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	cmdstr	string name exposed on CTRL
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype
[in]	min	minimum permitted integer value
[in]	max	maximum permitted integer value

#define CTRL_CMD_DEFINE_RO	(	cmdname,
		cmdstr
	)

Value:

static int get_##cmdname(struct ctrl_cmd *cmd, void *data);             \
static int set_##cmdname(struct ctrl_cmd *cmd, void *data)      \
{                                                                       \
        cmd->reply = "Read Only attribute";                             \
        return CTRL_CMD_ERROR;                                          \
}                                                                       \
static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *data) \
{                                                                       \
        cmd->reply = "Read Only attribute";                             \
        return 1;                                                       \
}                                                                       \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)

Define a read-only attribute.

Declares get, implements set+verify

Parameters

[in]	cmdname	symbol name of the command related functions/structures
[in]	cmdstr	string name exposed on CTRL

#define CTRL_CMD_DEFINE_STRING	(	cmdname,
		cmdstr,
		dtype,
		element
	)

Value:

CTRL_HELPER_GET_STRING(cmdname, dtype, element) \
	CTRL_HELPER_SET_STRING(cmdname, dtype, element) \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, NULL)

Helper to generate GET, SET, VERIFY + ctrl_cmd_element for string.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	cmdstr	string name exposed on CTRL
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype
[in]	min	minimum permitted integer value
[in]	max	maximum permitted integer value

#define CTRL_CMD_DEFINE_STRUCT	(	cmdname,
		cmdstr,
		verify_name
	)

Value:

static struct ctrl_cmd_element cmd_##cmdname = { \
        .name = cmdstr, \
        .get = &get_##cmdname, \
        .set = &set_##cmdname, \
        .verify = verify_name, \
}

Helper to generate static struct ctrl_cmd_element.

Parameters

[in]	cmdname	symbol name of the command related functions/structures
[in]	cmdstr	string name exposed on CTRL
[in]	verify_name	full symbol name of verification function

#define CTRL_CMD_DEFINE_WO	(	cmdname,
		cmdstr
	)

Value:

static int set_##cmdname(struct ctrl_cmd *cmd, void *data);                     \
static int get_##cmdname(struct ctrl_cmd *cmd, void *data)                      \
{                                                                               \
        cmd->reply = "Write Only attribute";                                    \
        return CTRL_CMD_ERROR;                                                  \
}                                                                               \
static int verify_##cmdname(struct ctrl_cmd *cmd, const char *val, void *data); \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)

Define a write-only attribute.

Declares set+verify, implements read call-back

Parameters

[in]	cmdname	symbol name of the command related functions/structures
[in]	cmdstr	string name exposed on CTRL

#define CTRL_CMD_DEFINE_WO_NOVRF	(	cmdname,
		cmdstr
	)

Value:

static int set_##cmdname(struct ctrl_cmd *cmd, void *data);                     \
static int get_##cmdname(struct ctrl_cmd *cmd, void *data)                      \
{                                                                               \
        cmd->reply = "Write Only attribute";                                    \
        return CTRL_CMD_ERROR;                                                  \
}                                                                               \
static int verify_##cmdname(struct ctrl_cmd *cmd, const char *val, void *data)  \
{                                                                               \
        return 0;                                                               \
}                                                                               \
CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_##cmdname)

Define a write-only attribute without verify.

Declares set, implements read+verify

Parameters

[in]	cmdname	symbol name of the command related functions/structures
[in]	cmdstr	string name exposed on CTRL

#define CTRL_CMD_ERROR -1

Referenced by ctrl_cmd_exec(), ctrl_cmd_handle(), get_counter(), get_fsm_inst_dump(), get_fsm_inst_parent_name(), get_fsm_inst_state(), get_fsm_inst_timer(), get_rate_ctr(), get_rate_ctr_group_idx(), set_counter(), and set_rate_ctr().

#define CTRL_CMD_HANDLED 0

Referenced by ctrl_cmd_exec_from_string(), ctrl_cmd_handle(), and ctrl_handle_msg().

#define CTRL_CMD_REPLY 1

Referenced by ctrl_cmd_exec(), ctrl_cmd_handle(), get_counter(), get_fsm_inst_dump(), get_fsm_inst_parent_name(), get_fsm_inst_state(), get_fsm_inst_timer(), get_rate_ctr(), and get_rate_ctr_group_idx().

#define ctrl_cmd_reply_printf	(	cmd,
		fmt,
		args...
	)	osmo_talloc_asprintf(cmd, cmd->reply, fmt, ## args)

Referenced by get_rate_ctr_group_idx().

#define CTRL_CMD_TRAP_ID "0"

Referenced by ctrl_cmd_send_trap().

#define CTRL_HELPER_GET_INT	(	cmdname,
		dtype,
		element
	)

Value:

static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
{ \
        dtype *node = cmd->node; \
        cmd->reply = talloc_asprintf(cmd, "%i", node->element); \
	if (!cmd->reply) { \
                cmd->reply = "OOM"; \
                return CTRL_CMD_ERROR; \
        } \
        return CTRL_CMD_REPLY; \
}

Helper to generate static GET function for integer.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype

#define CTRL_HELPER_GET_STRING	(	cmdname,
		dtype,
		element
	)

Value:

static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \
{ \
        dtype *data = cmd->node; \
        cmd->reply = talloc_asprintf(cmd, "%s", data->element); \
	if (!cmd->reply) { \
                cmd->reply = "OOM"; \
                return CTRL_CMD_ERROR; \
        } \
        return CTRL_CMD_REPLY; \
}

Helper to generate static GET function for string.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype

#define CTRL_HELPER_SET_INT	(	cmdname,
		dtype,
		element
	)

Value:

static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
{ \
        dtype *node = cmd->node; \
        int tmp = atoi(cmd->value); \
	node->element = tmp; \
        return get_##cmdname(cmd, _data); \
}

Helper to generate static SET function for integer.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype

#define CTRL_HELPER_SET_STRING	(	cmdname,
		dtype,
		element
	)

Value:

static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \
{ \
        dtype *data = cmd->node; \
	osmo_talloc_replace_string(cmd->node, &data->element, cmd->value); \
        return get_##cmdname(cmd, _data); \
}

Helper to generate static SET function for string.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	dtype	name of outer struct of user data
[in]	element	name of field within dtype

#define CTRL_HELPER_VERIFY_RANGE	(	cmdname,
		min,
		max
	)

Value:

static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *_data) \
{ \
        int tmp = atoi(value); \
	if ((tmp >= min)&&(tmp <= max)) { \
                return 0; \
        } \
        cmd->reply = "Input not within the range"; \
        return -1; \
}

Helper to generate static VERIFY unction validating a numeric range.

Parameters

[in]	cmdname	symbol name of the command related function
[in]	min	minimum permitted integer value
[in]	max	maximum permitted integer value

Enumeration Type Documentation

enum ctrl_node_type

The class of node at which a ctrl command is registered to.

Enumerator
CTRL_NODE_ROOT
CTRL_NODE_BTS
CTRL_NODE_TRX
CTRL_NODE_TS
CTRL_NODE_FSM
CTRL_NODE_FSM_INST
_LAST_CTRL_NODE

enum ctrl_type

Ctrl command types (GET, SET, ...)

Enumerator
CTRL_TYPE_UNKNOWN
CTRL_TYPE_GET
CTRL_TYPE_SET
CTRL_TYPE_GET_REPLY
CTRL_TYPE_SET_REPLY
CTRL_TYPE_TRAP
CTRL_TYPE_ERROR

Function Documentation

struct ctrl_cmd* ctrl_cmd_cpy	(	void *	ctx,
		struct ctrl_cmd *	cmd
	)

Perform a deepl copy of the given cmd, allocating memory from ctx.

Parameters

[in]	ctx	talloc context from which to allocate

References ctrl_cmd::id, ctrl_cmd::reply, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.

Referenced by ctrl_cmd_trap().

struct ctrl_cmd* ctrl_cmd_create	(	void *	ctx,
		enum ctrl_type	type
	)

Allocate a control command of given type.

Parameters

[in]	ctx	talloc context from which to allocate
[in]	type	command type to set after allocation

Returns: callee-allocated ctrl_cmd. Caller must talloc_free() it.

References ctrl_cmd::type.

Referenced by ctrl_cmd_send_trap().

int ctrl_cmd_def_is_zombie ( struct ctrl_cmd_def * cd )

Determine if the given deferred control command is still alive or a zombie.

Parameters

[in] cd deferred ctrl command state

Returns: 0 is cd is still alive; 1 if it's a zombie

References ctrl_cmd_def::cmd, ctrl_cmd_def::list, and llist_del().

struct ctrl_cmd_def* ctrl_cmd_def_make	(	const void *	ctx,
		struct ctrl_cmd *	cmd,
		void *	data,
		unsigned int	secs
	)

Build a deferred control command state and keep it the per-connection list of deferred commands.

This function is typically called by a ctrl command handler that wishes to defer returning a response. The reutnred state can later be used to check if the deferred command is still alive, and to respond to the specific command. This only works to defer the response to GET and SET.

Parameters

[in]	ctx	talloc context from whihc to allocate the ctrl_cmd_def
[in]	cmd	the control command whose response is deferred
[in]	data	opaque, user-defined pointer
[in]	secs	number of seconds until the command times out

Returns: callee-allocated ctrl_cmd_def

References ctrl_cmd::ccon, ctrl_cmd_def::cmd, data, ctrl_cmd_def::data, ctrl_connection::def_cmds, ctrl_cmd::defer, ctrl_cmd_def::list, and llist_add().

int ctrl_cmd_def_send ( struct ctrl_cmd_def * cd )

Send the response to a deferred ctrl command.

The command can only be a resply to a SET or a GET operation.

Parameters

[in] cd deferred ctrl command state

Returns: 0 if command sent successfully; negative on error

References ctrl_cmd::ccon, ctrl_cmd_def::cmd, ctrl_cmd_send(), CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, ctrl_cmd_def::list, llist_del(), ctrl_cmd::type, and ctrl_connection::write_queue.

int ctrl_cmd_exec	(	vector	vline,
		struct ctrl_cmd *	command,
		vector	node,
		void *	data
	)

Execute a given received command.

Parameters

[in]	vline	vector representing the available/registered commands
[in,out]	command	parsed received command to be executed
[in]	node	CTRL interface node
[in]	data	opaque data passed to verify(), get() and set() call-backs

Returns: CTRL_CMD_HANDLED or CTRL_CMD_REPLY; CTRL_CMD_ERROR on error

References CTRL_CMD_ERROR, ctrl_cmd_get_element_match(), CTRL_CMD_REPLY, CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, ctrl_cmd_element::get, ctrl_cmd::reply, ctrl_cmd_element::set, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd_element::verify.

Referenced by ctrl_cmd_handle().

int ctrl_cmd_install	(	enum ctrl_node_type	node,
		struct ctrl_cmd_element *	cmd
	)

Install a given command definition at a given CTRL node.

Parameters

[in]	node	CTRL node at whihc cmd is to be installed
[in]	cmd	command definition to be installed

Returns: 0 on success; negative on error

References create_cmd_struct(), DLCTRL, LOGL_ERROR, LOGP, ctrl_cmd_element::name, ctrl_cmd_element::strcmd, vector_init(), vector_lookup_ensure(), vector_set(), and vector_set_index().

Referenced by ctrl_init(), and osmo_fsm_ctrl_cmds_install().

struct msgb* ctrl_cmd_make ( struct ctrl_cmd * cmd )

Encode a given CTRL command from its parsed form into a message buffer.

Parameters

[in] cmd decoded/parsed form of to-be-encoded command

Returns: callee-allocated message buffer containing the encoded cmd; NULL on error

References CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, CTRL_TYPE_TRAP, DLCTRL, get_value_string(), ctrl_cmd::id, msgb::l2h, LOGL_ERROR, LOGL_NOTICE, LOGP, msg, msgb_alloc_headroom(), msgb_free(), msgb_put(), ctrl_cmd::reply, type, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.

Referenced by ctrl_cmd_send().

struct ctrl_cmd* ctrl_cmd_parse	(	void *	ctx,
		struct msgb *	msg
	)

Parse/Decode CTRL from Message buffers into command struct.

Parameters

[in]	ctx	talloc context from which to allocate
[in]	msg	message buffer containing command to be decoded

Returns: callee-allocated decoded CTRL command; NULL on allocation or other failure The caller is responsible to talloc_free() the returned struct pointer.

References ctrl_cmd_parse2(), CTRL_TYPE_ERROR, res, and ctrl_cmd::type.

struct ctrl_cmd* ctrl_cmd_parse2	(	void *	ctx,
		struct msgb *	msg
	)

Parse/Decode CTRL from Message buffers into command struct.

Parameters

[in]	ctx	talloc context from which to allocate
[in]	msg	message buffer containing command to be decoded

Returns: callee-allocated decoded CTRL command; NULL on allocation failure, ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error. The caller is responsible to talloc_free() the returned struct pointer. If information of the origin of the ERROR cmd returned is required (received or local parsing failure), use ctrl_cmd_parse3 instead.

References ctrl_cmd_parse3().

Referenced by ctrl_cmd_exec_from_string(), and ctrl_cmd_parse().

struct ctrl_cmd* ctrl_cmd_parse3	(	void *	ctx,
		struct msgb *	msg,
		bool *	parse_failed
	)

Parse/Decode CTRL from Message buffers into command struct.

Parameters

[in]	ctx	talloc context from which to allocate
[in]	msg	message buffer containing command to be decoded
[out]	parse_failed	Whether returned ERROR cmd was generatd locally (due to parse failure) or was received.

Returns: callee-allocated decoded CTRL command; NULL on allocation failure, ctrl->type == CTRL_TYPE_ERROR and an error message in ctrl->reply on any error. The caller is responsible to talloc_free() the returned struct pointer.

References CTRL_TYPE_ERROR, CTRL_TYPE_GET, CTRL_TYPE_GET_REPLY, CTRL_TYPE_SET, CTRL_TYPE_SET_REPLY, CTRL_TYPE_TRAP, CTRL_TYPE_UNKNOWN, DLCTRL, get_string_value(), get_value_string(), ctrl_cmd::id, id_str_valid(), msgb::l2h, LOGL_DEBUG, LOGL_ERROR, LOGL_NOTICE, LOGP, msgb_put_u8(), OSMO_ASSERT, osmo_escape_str(), osmo_separated_identifiers_valid(), ctrl_cmd::reply, REPLY_CASE, ctrl_cmd::type, ctrl_cmd::value, and ctrl_cmd::variable.