libwimaxll: update documentation after pipe removal

Signed-off-by: Inaky Perez-Gonzalez <inaky@linux.intel.com>

4 files changed, 41 insertions, 74 deletions

diff --git a/lib/genl.c b/lib/genl.c
index 9dc3f09..71975c0 100644
--- a/lib/genl.c
+++ b/lib/genl.c
@@ -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.
  *