diff options
| -rw-r--r-- | lib/genl.c | 8 | ||||
| -rw-r--r-- | lib/op-msg.c | 86 | ||||
| -rw-r--r-- | lib/op-open.c | 5 | ||||
| -rw-r--r-- | lib/re-state-change.c | 16 |
4 files changed, 41 insertions, 74 deletions
@@ -105,10 +105,10 @@ static int family_handler(struct nl_msg *msg, void *_arg) /** * Enumerates the list of available multicast groups for a family * - * @handle: netlink handle to use for querying the list - * @family: name of family to query for multicast groups - * @cb: callback function to call with each multicast group's information. - * @priv: pointer to pass to the callback function + * \param handle netlink handle to use for querying the list + * \param family name of family to query for multicast groups + * \param cbf callback function to call with each multicast group's information. + * \param priv pointer to pass to the callback function * * Returns: 0 if ok, < 0 errno code on error. * diff --git a/lib/op-msg.c b/lib/op-msg.c index bebb0bc..4e51894 100644 --- a/lib/op-msg.c +++ b/lib/op-msg.c @@ -38,25 +38,25 @@ * This is a payload agnostic message interface for communication * between the WiMAX kernel drivers and user space applications. * - * This interfaces builds on the \e kernel-to-user unidirectional \ref - * the_pipe_interface_group "pipe interface". It writes data to the default - * \e message pipe by sending it to the WiMAX kernel stack, which - * passes it to the driver using the \e wimax_dev->op_msg_from_user() - * call. + * It writes messages (wimax_msg_write()) by sending them to the WiMAX + * kernel stack, which passes it to the driver using the \e + * wimax_dev->op_msg_from_user() call. * - * Only the default \e message pipe is bidirectional; WiMAX kernel - * drivers receive messages sent with wimax_msg_write(). + * To write messages to the driver: + * + * @code + * wimaxll_msg_write(wmx, PIPE_NAME, buf, buf_size); + * @endcode * - * \note The wimaxll_msg_fd() and wimaxll_msg_read() functions operate - * on the default \e message pipe, being convenience functions for - * wimaxll_pipe_fd() and wimaxll_pipe_msg_read(). + * where \a buf points to where the message is stored. \e PIPE_NAME + * can be NULL. It is passed verbatim to the receiver. * * To wait for a message from the driver: * * @code * void *msg; * ... - * size = wimaxll_msg_read(wmx, &msg); + * size = wimaxll_msg_read(wmx, PIPE_NAME, &msg); * @endcode * * Note this call is synchronous and blocking, and won't timeout. You @@ -72,60 +72,25 @@ * wimaxll_msg_free(msg); * @endcode * - * To write messages to the driver: - * - * @code - * wimaxll_msg_write(wmx, buf, buf_size); - * @endcode - * - * where \a buf points to where the message is stored. - * - * \note Messages can be written to the driver \e only over the - * default \e message pipe. Thus, no wimax_pipe_msg_write() - * function is available. - * * All functions return negative \a errno codes on error. * * To integrate message reception into a mainloop, \ref callbacks * "callbacks" and select() should be used. The file descriptor * associated to the default \e message \e pipe can be obtained with - * wimaxll_msg_fd(). When there is activity on the file descriptor, - * wimaxll_pipe_read() should be called on the default pipe: + * wimaxll_recv_fd(). When there is activity on the file descriptor, + * wimaxll_recv() should be called: * * \code - * wimax_pipe_read(wmx, wimax_msg_pipe_id(wmx)); + * wimax_recv(wmx); * \endcode * * this will, as explained in \ref receiving, for each received * notification, execute its callback. * * The callback for reception of messages from the WiMAX kernel stack - * can be set with wimaxll_pipe_set_cb_msg_to_user() (using as \e - * pipe_id the value returned by wimax_msg_pipe_id()). For detailed + * can be set with wimaxll_set_cb_msg_to_user()). For detailed * information on the message reception callback, see the definition * of \ref wimaxll_msg_to_user_cb_f. - * - * The kernel WiMAX stack allows drivers to create any number of pipes - * on which to send information (messages) to user space. This - * interface provides means to read those messages, which are mostly - * device specific. - * - * This is a lower level interface than \ref the_messaging_interface - * "the messaging interface"; however, it operates similarly. - * - * @code - * void *msg; - * ... - * wimaxll_msg_read(wmx, "PIPE NAME", &msg); - * ... - * wimaxll_msg_free(msg); - * ... - * @endcode - * - * More information about the details of this interface can be found - * \ref the_pipe_interface_group "here". - * - * \note These pipes are not bidirectional. */ #define _GNU_SOURCE #include <sys/types.h> @@ -153,7 +118,6 @@ * * Authoritative reference for this is at the kernel code, * drivers/net/wimax/op-msg.c. - * */ static struct nla_policy wimaxll_gnl_msg_from_user_policy[WIMAX_GNL_ATTR_MAX + 1] = { @@ -175,9 +139,10 @@ struct nla_policy wimaxll_gnl_msg_from_user_policy[WIMAX_GNL_ATTR_MAX + 1] = { * \return \c enum nl_cb_action * * wimaxll_recv() calls libnl's nl_recvmsgs() to receive messages; - * when a valid message is received, it goes into a loop that selects - * a callback to run for each type of message and it will call this - * function. + * when a valid message is received, wimax_gnl__cb() that selects a + * callback to run for each type of message and it will call this + * function to actually do it. If no message handling callback is set, + * this is not called. * * This "netlink" callback will just de-marshall the arguments and * call the callback set by the user with wimaxll_set_cb_msg_to_user(). @@ -342,7 +307,7 @@ out: * \param pipe_name Name of the pipe for which we want to read a * message. If NULL, only messages from the default pipe (without * pipe name) will be received. To receive messages from any pipe, - * use pipe ~NULL. + * use pipe WIMAX_PIPE_ANY. * \param buf Somewhere where to store the pointer to the message data. * \return If successful, a positive (and \c *buf set) or zero size of * the message; on error, a negative \a errno code (\c buf @@ -416,10 +381,9 @@ void wimaxll_msg_free(void *msg) * * \param wmx wimax device descriptor * \param pipe_name Name of the pipe for which to send the message; - * NULL to send it to no pipe in particular. - * \param buf Pointer to the wimax message. + * NULL means adding no destination pipe. + * \param buf Pointer to the message. * \param size size of the message. - * * \return 0 if ok < 0 errno code on error. On error it is assumed * the message wasn't delivered. * @@ -490,6 +454,9 @@ error_msg_alloc: /** * Get the callback and priv pointer for a MSG_TO_USER message * + * Get the callback and private pointer that will be called by + * wimaxll_recv() when a MSG_TO_USER is received over generic netlink. + * * \param wmx WiMAX handle. * \param cb Where to store the current callback function. * \param context Where to store the private data pointer passed to the @@ -509,6 +476,9 @@ void wimaxll_get_cb_msg_to_user( /** * Set the callback and priv pointer for a MSG_TO_USER message * + * Set the callback and private pointer that will be called by + * wimaxll_recv() when a MSG_TO_USER is received over generic netlink. + * * \param wmx WiMAX handle. * \param cb Callback function to set * \param context Private data pointer to pass to the callback diff --git a/lib/op-open.c b/lib/op-open.c index 583d360..8a43ac9 100644 --- a/lib/op-open.c +++ b/lib/op-open.c @@ -110,9 +110,8 @@ static * multiplex and handle messages that are known to the library. If the * message is unknown, do nothing other than setting -ENODATA. * - * When reading from a pipe with wimaxll_pipe_read(), -ENODATA is - * considered a retryable error -- effectively, the message is - * skipped. + * In wimaxll_recv(), -ENODATA is considered a retryable error -- + * effectively, the message is skipped. * * \fn int wimaxll_gnl_cb(struct nl_msg *msg, void *_ctx) */ diff --git a/lib/re-state-change.c b/lib/re-state-change.c index faa90c8..7baab12 100644 --- a/lib/re-state-change.c +++ b/lib/re-state-change.c @@ -57,9 +57,9 @@ * @endcode * * and then wait for notifications to be available (see \ref receiving - * "receiving with select()"). When data is available and - * wimax_pipe_read() called to process them, the callback will be - * executed for each state change notification. + * "receiving with select()"). When data is available and wimax_recv() + * is called to process it, the callback will be executed for each + * state change notification. * * Applications can query the current callback set for the state * change notifications with wimaxll_get_cb_state_change(). @@ -114,8 +114,7 @@ struct nla_policy wimaxll_gnl_re_state_change_policy[WIMAX_GNL_ATTR_MAX + 1] = { * * This just expects a _RE_STATE_CHANGE message, whose payload is what * has to be passed to the caller. We just extract the data and call - * the callback defined by the caller to wimaxll_mc_rx_read() (or - * wimaxll_pipe_read()). + * the callback defined in the handle. */ int wimaxll_gnl_handle_state_change(struct wimaxll_handle *wmx, struct nl_msg *msg) @@ -265,10 +264,9 @@ int wimaxll_cb_state_change(struct wimaxll_handle *wmx, * Waits for the WiMAX device to change state and reports said state * change. * - * Internally, this function uses wimax_pipe_read() on the default \e - * message pipe, which means that on reception (from the kernel) of - * notifications other than state change, any callbacks that are set - * for them will be executed. + * Internally, this function uses wimax_recv() , which means that on + * reception (from the kernel) of notifications other than state + * change, any callbacks that are set for them will be executed. * * \note This is a blocking call. * |