| /*! \file control_cmd.h */ |
| |
| #pragma once |
| |
| #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> |
| |
| #define CTRL_CMD_ERROR -1 |
| #define CTRL_CMD_HANDLED 0 |
| #define CTRL_CMD_REPLY 1 |
| #define CTRL_CMD_TRAP_ID "0" |
| |
| struct ctrl_handle; |
| |
| /*! The class of node at which a ctrl command is registered to */ |
| enum ctrl_node_type { |
| CTRL_NODE_ROOT, /* Root elements */ |
| CTRL_NODE_BTS, /* BTS specific (net.btsN.) */ |
| CTRL_NODE_TRX, /* TRX specific (net.btsN.trxM.) */ |
| CTRL_NODE_TS, /* TS specific (net.btsN.trxM.tsI.) */ |
| CTRL_NODE_FSM, /* Finite State Machine (description) */ |
| CTRL_NODE_FSM_INST, /* Finite State Machine (instance) */ |
| _LAST_CTRL_NODE |
| }; |
| |
| /*! Ctrl command types (GET, SET, ...) */ |
| 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 |
| }; |
| |
| /*! human-readable string names for \ref ctrl_type */ |
| extern const struct value_string ctrl_type_vals[]; |
| |
| /*! Represents a single ctrl connection */ |
| struct ctrl_connection { |
| struct llist_head list_entry; |
| |
| /*! The queue for sending data back */ |
| struct osmo_wqueue write_queue; |
| |
| /*! Buffer for partial input data */ |
| struct msgb *pending_msg; |
| |
| /*! Callback if the connection was closed */ |
| void (*closed_cb)(struct ctrl_connection *conn); |
| |
| /*! Pending commands for this connection */ |
| struct llist_head cmds; |
| |
| /*! Pending deferred command responses for this connection */ |
| struct llist_head def_cmds; |
| }; |
| |
| struct ctrl_cmd_def; |
| |
| /*! Represents a single ctrl command after parsing */ |
| struct ctrl_cmd { |
| /*! connection through which the command was received */ |
| struct ctrl_connection *ccon; |
| /*! command type */ |
| enum ctrl_type type; |
| char *id; |
| /*! node of the specified variable */ |
| void *node; |
| /*! name of the variable */ |
| char *variable; |
| /*! value of the specified CTRL variable */ |
| char *value; |
| /*! respnse message string */ |
| char *reply; |
| /*! state representing deferred (async) response, if any */ |
| struct ctrl_cmd_def *defer; |
| }; |
| |
| #define ctrl_cmd_reply_printf(cmd, fmt, args ...) \ |
| osmo_talloc_asprintf(cmd, cmd->reply, fmt, ## args) |
| |
| struct ctrl_cmd_struct { |
| int nr_commands; |
| char **command; |
| }; |
| |
| /*! Implementation of a given CTRL command. This is what a program registers |
| * using \r ctrl_cmd_install in order to implement a given control variable. */ |
| struct ctrl_cmd_element { |
| /*! textual name/id of the CTRL command */ |
| const char *name; |
| struct ctrl_cmd_struct strcmd; |
| /*! call-back function implementing the SET operation */ |
| int (*set)(struct ctrl_cmd *cmd, void *data); |
| /*! call-back function implementing the GET operation */ |
| int (*get)(struct ctrl_cmd *cmd, void *data); |
| /*! call-back function to validate a value; called before SET */ |
| int (*verify)(struct ctrl_cmd *cmd, const char *value, void *data); |
| }; |
| |
| struct ctrl_cmd_map { |
| char *cmd; |
| enum ctrl_type type; |
| }; |
| |
| /* deferred control command, i.e. responded asynchronously */ |
| struct ctrl_cmd_def { |
| struct llist_head list; /* ctrl_connection.def_cmds */ |
| struct ctrl_cmd *cmd; |
| void *data; /* opaque user data */ |
| }; |
| |
| struct ctrl_cmd_def * |
| ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned int secs); |
| int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd); |
| int ctrl_cmd_def_send(struct ctrl_cmd_def *cd); |
| |
| int ctrl_cmd_exec(vector vline, struct ctrl_cmd *command, vector node, void *data); |
| int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd); |
| int ctrl_cmd_send(struct osmo_wqueue *queue, struct ctrl_cmd *cmd); |
| int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd); |
| struct ctrl_cmd *ctrl_cmd_parse3(void *ctx, struct msgb *msg, bool *parse_failed); |
| struct ctrl_cmd *ctrl_cmd_parse2(void *ctx, struct msgb *msg); |
| struct ctrl_cmd *ctrl_cmd_parse(void *ctx, struct msgb *msg); |
| struct msgb *ctrl_cmd_make(struct ctrl_cmd *cmd); |
| struct ctrl_cmd *ctrl_cmd_cpy(void *ctx, struct ctrl_cmd *cmd); |
| struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type); |
| struct ctrl_cmd *ctrl_cmd_trap(struct ctrl_cmd *cmd); |
| |
| /*! Helper to generate static struct ctrl_cmd_element |
| * \param[in] cmdname symbol name of the command related functions/structures |
| * \param[in] cmdstr string name exposed on CTRL |
| * \param[in] verify_name full symbol name of verification function */ |
| #define CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, verify_name) \ |
| static struct ctrl_cmd_element cmd_##cmdname = { \ |
| .name = cmdstr, \ |
| .get = &get_##cmdname, \ |
| .set = &set_##cmdname, \ |
| .verify = verify_name, \ |
| } |
| |
| /*! Helper to generate static GET function for integer |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype */ |
| #define CTRL_HELPER_GET_INT(cmdname, dtype, element) \ |
| 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 SET function for integer |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype */ |
| #define CTRL_HELPER_SET_INT(cmdname, dtype, element) \ |
| 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 VERIFY unction validating a numeric range |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] min minimum permitted integer value |
| * \param[in] max maximum permitted integer value */ |
| #define CTRL_HELPER_VERIFY_RANGE(cmdname, min, max) \ |
| 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 GET, SET, VERIFY + ctrl_cmd_element for integer |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] cmdstr string name exposed on CTRL |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype |
| * \param[in] min minimum permitted integer value |
| * \param[in] max maximum permitted integer value */ |
| #define CTRL_CMD_DEFINE_RANGE(cmdname, cmdstr, dtype, element, min, max) \ |
| 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 static GET function for string |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype */ |
| #define CTRL_HELPER_GET_STRING(cmdname, dtype, element) \ |
| 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 SET function for string |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype */ |
| #define CTRL_HELPER_SET_STRING(cmdname, dtype, element) \ |
| 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 GET, SET, VERIFY + ctrl_cmd_element for string |
| * \param[in] cmdname symbol name of the command related function |
| * \param[in] cmdstr string name exposed on CTRL |
| * \param[in] dtype name of outer struct of user data |
| * \param[in] element name of field within \a dtype */ |
| #define CTRL_CMD_DEFINE_STRING(cmdname, cmdstr, dtype, element) \ |
| CTRL_HELPER_GET_STRING(cmdname, dtype, element) \ |
| CTRL_HELPER_SET_STRING(cmdname, dtype, element) \ |
| CTRL_CMD_DEFINE_STRUCT(cmdname, cmdstr, NULL) |
| |
| /*! Declare a read-write attribute. Declares get, set, verify. |
| * \param[in] cmdname symbol name of the command related functions/structures |
| * \param[in] cmdstr string name exposed on CTRL */ |
| #define CTRL_CMD_DEFINE(cmdname, cmdstr) \ |
| 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) |
| |
| /*! Define a read-only attribute. Declares get, implements set+verify |
| * \param[in] cmdname symbol name of the command related functions/structures |
| * \param[in] cmdstr string name exposed on CTRL */ |
| #define CTRL_CMD_DEFINE_RO(cmdname, cmdstr) \ |
| 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 write-only attribute. Declares set+verify, implements read call-back |
| * \param[in] cmdname symbol name of the command related functions/structures |
| * \param[in] cmdstr string name exposed on CTRL */ |
| #define CTRL_CMD_DEFINE_WO(cmdname, cmdstr) \ |
| 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 without verify. Declares set, implements read+verify |
| * \param[in] cmdname symbol name of the command related functions/structures |
| * \param[in] cmdstr string name exposed on CTRL */ |
| #define CTRL_CMD_DEFINE_WO_NOVRF(cmdname, cmdstr) \ |
| 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) |
| |
| struct gsm_network; |