ctrl: Add doxygen API documentation; generate html from it

Closes: OS#3293
Change-Id: I8dc2f24d4bf557ff7bb0f2f46881f9f8d9d7f86f
changes/32/9332/3
Harald Welte 4 years ago
parent ed6057841d
commit b4186824c2
  1. 1716
      Doxyfile.ctrl.in
  2. 10
      Makefile.am
  3. 1
      configure.ac
  4. 83
      include/osmocom/ctrl/control_cmd.h
  5. 49
      src/ctrl/control_cmd.c
  6. 22
      src/ctrl/control_if.c

File diff suppressed because it is too large Load Diff

@ -35,6 +35,7 @@ $(html_DATA): $(top_builddir)/doc/core/html/index.html \
$(top_builddir)/doc/vty/html/index.html \
$(top_builddir)/doc/codec/html/index.html \
$(top_builddir)/doc/coding/html/index.html \
$(top_builddir)/doc/ctrl/html/index.html \
$(top_builddir)/doc/gb/html/index.html
cd $(top_builddir)/doc && tar cf html.tar */html
@ -62,6 +63,11 @@ $(top_builddir)/doc/coding/html/index.html: Doxyfile.coding
mkdir -p doc/coding
$(DOXYGEN) Doxyfile.coding
$(top_builddir)/doc/ctrl/html/index.html: $(SOURCES) Doxyfile.ctrl
@rm -rf doc/ctrl
mkdir -p doc/ctrl
$(DOXYGEN) Doxyfile.ctrl
$(top_builddir)/doc/gb/html/index.html: $(SOURCES) Doxyfile.gb
@rm -rf doc/gb
mkdir -p doc/gb
@ -71,9 +77,9 @@ install-data-hook:
cd $(DESTDIR)$(htmldir) && tar xf html.tar && rm -f html.tar
uninstall-hook:
cd $(DESTDIR)$(htmldir) && rm -rf {core,gsm,vty,codec,coding,gb}
cd $(DESTDIR)$(htmldir) && rm -rf {core,gsm,vty,codec,coding,ctrl,gb}
DX_CLEAN = doc/{core,gsm,vty,codec,coding,gb}/html/search/* doc/{core,gsm,vty,codec,coding,gb}/{html,latex}/* doc/html.tar doc/{core,gsm,vty,codec,coding,gb}/doxygen_sqlite3.db doc/*.tag
DX_CLEAN = doc/{core,gsm,vty,codec,coding,ctrl,gb}/html/search/* doc/{core,gsm,vty,codec,coding,ctrl,gb}/{html,latex}/* doc/html.tar doc/{core,gsm,vty,codec,coding,ctrl,gb}/doxygen_sqlite3.db doc/*.tag
endif
MOSTLYCLEANFILES = $(DX_CLEAN)

@ -371,4 +371,5 @@ AC_OUTPUT(
Doxyfile.codec
Doxyfile.coding
Doxyfile.gb
Doxyfile.ctrl
Makefile)

@ -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) \

@ -89,6 +89,12 @@ static struct ctrl_cmd_element *ctrl_cmd_get_element_match(vector vline, vector
return NULL;
}
/*! Execute a given received command
* \param[in] vline vector representing the available/registered commands
* \param[inout] command parsed received command to be executed
* \param[in] node CTRL interface node
* \param[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 */
int ctrl_cmd_exec(vector vline, struct ctrl_cmd *command, vector node, void *data)
{
int ret = CTRL_CMD_ERROR;
@ -200,6 +206,10 @@ failure:
talloc_free(cmd->command);
}
/*! Install a given command definition at a given CTRL node.
* \param[in] node CTRL node at whihc \a cmd is to be installed
* \param[in] cmd command definition to be installed
* \returns 0 on success; negative on error */
int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
{
vector cmds_vec;
@ -221,6 +231,10 @@ int ctrl_cmd_install(enum ctrl_node_type node, struct ctrl_cmd_element *cmd)
return 0;
}
/*! Allocate a control command of given \a type.
* \param[in] ctx talloc context from which to allocate
* \param[in] type command type to set after allocation
* \returns callee-allocated \ref ctrl_cmd. Caller must talloc_free() it. */
struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type)
{
struct ctrl_cmd *cmd;
@ -233,6 +247,10 @@ struct ctrl_cmd *ctrl_cmd_create(void *ctx, enum ctrl_type type)
return cmd;
}
/*! Perform a deepl copy of the given \a cmd, allocating memory from \a ctx.
* \param[in] ctx talloc context from which to allocate
* \param[in cmd CTRL command to be copied
* \returns deep copy of \a cmd on success; NULL on error */
struct ctrl_cmd *ctrl_cmd_cpy(void *ctx, struct ctrl_cmd *cmd)
{
struct ctrl_cmd *cmd2;
@ -269,7 +287,10 @@ err:
return NULL;
}
/*! Parse CTRL command struct from msgb, return NULL on any error.
/*! Parse/Decode CTRL from \ref msgb into command struct.
* \param[in] ctx talloc context from which to allocate
* \param[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. */
struct ctrl_cmd *ctrl_cmd_parse(void *ctx, struct msgb *msg)
{
@ -290,8 +311,11 @@ static bool id_str_valid(const char *str)
return true;
}
/*! Parse CTRL command struct from msgb, return ctrl->type == CTRL_TYPE_ERROR and an error message in
* ctrl->reply on any error.
/*! Parse/Decode CTRL from \ref msgb into command struct.
* \param[in] ctx talloc context from which to allocate
* \param[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. */
struct ctrl_cmd *ctrl_cmd_parse2(void *ctx, struct msgb *msg)
{
@ -466,6 +490,9 @@ err:
return cmd;
}
/*! Encode a given CTRL command from its parsed form into a message buffer.
* \param[in] cmd decoded/parsed form of to-be-encoded command
* \returns callee-allocated message buffer containing the encoded \a cmd; NULL on error */
struct msgb *ctrl_cmd_make(struct ctrl_cmd *cmd)
{
struct msgb *msg;
@ -556,6 +583,15 @@ err:
return NULL;
}
/*! 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.
* \param[in] ctx talloc context from whihc to allocate the ctrl_cmd_def
* \param[in] cmd the control command whose response is deferred
* \param[in] data opaque, user-defined pointer
* \param[in] secs number of seconds until the command times out
* \returns callee-allocated ctrl_cmd_def */
struct ctrl_cmd_def *
ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned int secs)
{
@ -576,6 +612,9 @@ ctrl_cmd_def_make(const void *ctx, struct ctrl_cmd *cmd, void *data, unsigned in
return cd;
}
/*! Determine if the given deferred control command is still alive or a zombie.
* \param[in] cd deferred ctrl command state
* \returns 0 is \a cd is still alive; 1 if it's a zombie */
int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd)
{
/* luckily we're still alive */
@ -589,6 +628,10 @@ int ctrl_cmd_def_is_zombie(struct ctrl_cmd_def *cd)
return 1;
}
/*! Send the response to a deferred ctrl command.
* The command can only be a resply to a SET or a GET operation.
* \param[in] cd deferred ctrl command state
* \returns 0 if command sent successfully; negative on error */
int ctrl_cmd_def_send(struct ctrl_cmd_def *cd)
{
struct ctrl_cmd *cmd = cd->cmd;

@ -75,6 +75,11 @@ struct lookup_helper {
};
static LLIST_HEAD(ctrl_lookup_helpers);
/*! Parse ascii-encoded decimal number at vline[i]
* \param[in] vline vector containing a tokenized line
* \param[in] i index into the vector \a vline
* \param[out] num parsed decimal integer number at vline[i]
* \returns 1 on success; 0 in case of error */
int ctrl_parse_get_num(vector vline, int i, long *num)
{
char *token, *tmp;
@ -94,7 +99,10 @@ int ctrl_parse_get_num(vector vline, int i, long *num)
return 1;
}
/* Send command to all */
/*! Send a CTRL command to all connections.
* \param[in] ctrl global control handle
* \param[in] cmd command to send to all connections in \ctrl
* \returns number of times the command has been sent */
int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd)
{
struct ctrl_connection *ccon;
@ -109,6 +117,10 @@ int ctrl_cmd_send_to_all(struct ctrl_handle *ctrl, struct ctrl_cmd *cmd)
return ret;
}
/*! Encode a CTRL command and append it to the given write queue
* \param[inout] queue write queue to which encoded \a cmd shall be appended
* \param[in] cmd decoded command representation
* \returns 0 in case of success; negative on error */
int ctrl_cmd_send(struct osmo_wqueue *queue, struct ctrl_cmd *cmd)
{
int ret;
@ -152,6 +164,9 @@ int ctrl_cmd_send_trap(struct ctrl_handle *ctrl, const char *name, char *value)
return r;
}
/*! Copy given \a cmd and convert copy to CTRL_TYPE_TRAP.
* \param[in] cmd command to be copied
* \returns pointer to newly-allocated copy of type TRAP. Allocated as sibling of \a cmd */
struct ctrl_cmd *ctrl_cmd_trap(struct ctrl_cmd *cmd)
{
struct ctrl_cmd *trap;
@ -361,6 +376,11 @@ close_fd:
return -EBADF;
}
/*! Handle a received CTRL command contained in a \ref msgb.
* \param[in] ctrl CTRL interface handle
* \param[in] ccon CTRL connection through which the command was received
* \param[in] msg message buffer containing CTRL command including IPA+IPA_EXT headers
* \returns 0 on success; negative on error */
int ctrl_handle_msg(struct ctrl_handle *ctrl, struct ctrl_connection *ccon, struct msgb *msg)
{
struct ctrl_cmd *cmd;

Loading…
Cancel
Save