[ovs-discuss] [PATCH 20/20] lxnetdev: Document.

Ben Pfaff blp at nicira.com
Fri Jul 24 21:20:03 UTC 2009


---
 lib/netdev-linux.c |   15 +++++++++++++++
 lib/netdev-linux.h |   12 ++++++++++--
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/lib/netdev-linux.c b/lib/netdev-linux.c
index b9f2af8..2021333 100644
--- a/lib/netdev-linux.c
+++ b/lib/netdev-linux.c
@@ -1600,6 +1600,15 @@ static void lxnetdev_report_change(const struct nlmsghdr *,
                                    struct nlattr *attrs[]);
 static void lxnetdev_report_notify_error(void);
 
+/* Registers 'cb' to be called with auxiliary data 'aux' with network device
+ * change notifications.  The notifier is stored in 'notifier', which the
+ * caller must not modify or free.
+ *
+ * This is probably not the function that you want.  You should probably be
+ * using dpif_port_poll() or netdev_monitor_create(), which unlike this
+ * function are not Linux-specific.
+ *
+ * Returns 0 if successful, otherwise a positive errno value. */
 int
 lxnetdev_notifier_register(struct lxnetdev_notifier *notifier,
                            lxnetdev_notify_func *cb, void *aux)
@@ -1624,6 +1633,8 @@ lxnetdev_notifier_register(struct lxnetdev_notifier *notifier,
     return 0;
 }
 
+/* Cancels notification on 'notifier', which must have previously been
+ * registered with lxnetdev_notifier_register(). */
 void
 lxnetdev_notifier_unregister(struct lxnetdev_notifier *notifier)
 {
@@ -1634,6 +1645,8 @@ lxnetdev_notifier_unregister(struct lxnetdev_notifier *notifier)
     }
 }
 
+/* Calls all of the registered notifiers, passing along any as-yet-unreported
+ * netdev change events. */
 void
 lxnetdev_notifier_run(void)
 {
@@ -1676,6 +1689,8 @@ lxnetdev_notifier_run(void)
     }
 }
 
+/* Causes poll_block() to wake up when network device change notifications are
+ * ready. */
 void
 lxnetdev_notifier_wait(void)
 {
diff --git a/lib/netdev-linux.h b/lib/netdev-linux.h
index 3b37385..402f993 100644
--- a/lib/netdev-linux.h
+++ b/lib/netdev-linux.h
@@ -22,6 +22,8 @@
 
 #include "list.h"
 
+/* A digested version of an rtnetlink message sent down by the kernel to
+ * indicate that a network device has been created or destroyed or changed.  */
 struct lxnetdev_change {
     /* Copied from struct nlmsghdr. */
     int nlmsg_type;             /* e.g. RTM_NEWLINK, RTM_DELLINK. */
@@ -34,9 +36,15 @@ struct lxnetdev_change {
     int master_ifindex;         /* Ifindex of datapath master (0 if none). */
 };
 
-typedef void lxnetdev_notify_func(const struct lxnetdev_change *,
-                                      void *aux);
+/* Function called to report that a netdev has changed.  'change' describes the
+ * specific change.  It may be null if the buffer of change information
+ * overflowed, in which case the function must assume that every device may
+ * have changed.  'aux' is as specified in the call to
+ * lxnetdev_notifier_register().  */
+typedef void lxnetdev_notify_func(const struct lxnetdev_change *change,
+                                  void *aux);
 
+/* A notifier.  Opaque. */
 struct lxnetdev_notifier {
     struct list node;
     lxnetdev_notify_func *cb;
-- 
1.6.3.3





More information about the discuss mailing list