From b4186824c20cbb5a18963d737f47718aed791e33 Mon Sep 17 00:00:00 2001 From: Harald Welte Date: Sat, 26 May 2018 17:25:11 +0200 Subject: ctrl: Add doxygen API documentation; generate html from it Closes: OS#3293 Change-Id: I8dc2f24d4bf557ff7bb0f2f46881f9f8d9d7f86f --- include/osmocom/ctrl/control_cmd.h | 83 +++++++++++++++++++++++++++++++++++--- 1 file changed, 77 insertions(+), 6 deletions(-) (limited to 'include') diff --git a/include/osmocom/ctrl/control_cmd.h b/include/osmocom/ctrl/control_cmd.h index a5df753d..08376f3c 100644 --- a/include/osmocom/ctrl/control_cmd.h +++ b/include/osmocom/ctrl/control_cmd.h @@ -15,6 +15,7 @@ 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.) */ @@ -25,6 +26,7 @@ enum ctrl_node_type { _LAST_CTRL_NODE }; +/*! Ctrl command types (GET, SET, ...) */ enum ctrl_type { CTRL_TYPE_UNKNOWN, CTRL_TYPE_GET, @@ -35,37 +37,47 @@ enum ctrl_type { 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 */ + /*! The queue for sending data back */ struct osmo_wqueue write_queue; - /* Buffer for partial input data */ + /*! Buffer for partial input data */ struct msgb *pending_msg; - /* Callback if the connection was closed */ + /*! Callback if the connection was closed */ void (*closed_cb)(struct ctrl_connection *conn); - /* Pending commands for this connection */ + /*! Pending commands for this connection */ struct llist_head cmds; - /* Pending deferred commands for this connection */ + /*! 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; }; @@ -77,11 +89,17 @@ struct ctrl_cmd_struct { 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); }; @@ -113,6 +131,10 @@ 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, \ @@ -121,6 +143,10 @@ static struct ctrl_cmd_element cmd_##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) \ { \ @@ -132,6 +158,11 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \ } \ 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) \ { \ @@ -140,6 +171,11 @@ static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \ 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) \ { \ @@ -151,12 +187,23 @@ static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *_data 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) \ { \ @@ -168,6 +215,11 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *_data) \ } \ 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) \ { \ @@ -175,17 +227,31 @@ static int set_##cmdname(struct ctrl_cmd *cmd, void *_data) \ 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 + * \param[in] min minimum permitted integer value + * \param[in] max maximum permitted integer value */ #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) \ @@ -200,6 +266,9 @@ static int verify_##cmdname(struct ctrl_cmd *cmd, const char *value, void *data) } \ 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) \ @@ -210,7 +279,9 @@ static int get_##cmdname(struct ctrl_cmd *cmd, void *data) \ 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) \ -- cgit v1.2.3