summaryrefslogtreecommitdiffstats
path: root/include
diff options
context:
space:
mode:
authorHarald Welte <laforge@gnumonks.org>2018-05-26 17:25:11 +0200
committerHarald Welte <laforge@gnumonks.org>2018-05-26 21:58:15 +0200
commitb4186824c20cbb5a18963d737f47718aed791e33 (patch)
tree419bd2c22ef95cc93e7c6533e498e8beb02d0de4 /include
parented6057841dd094f95efebbeae51a85bd0879463f (diff)
ctrl: Add doxygen API documentation; generate html from it
Closes: OS#3293 Change-Id: I8dc2f24d4bf557ff7bb0f2f46881f9f8d9d7f86f
Diffstat (limited to 'include')
-rw-r--r--include/osmocom/ctrl/control_cmd.h83
1 files changed, 77 insertions, 6 deletions
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) \