From d81c0ac56d42039d9bccbf4a65d4eb18f9fa654b Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@nicira.com>
Date: Tue, 28 Jul 2009 12:38:14 -0700
Subject: [PATCH] rtnetlink: Document.

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

diff --git a/lib/netdev-linux.c b/lib/netdev-linux.c
index fbca67601..95d9d9072 100644
--- a/lib/netdev-linux.c
+++ b/lib/netdev-linux.c
@@ -1605,6 +1605,15 @@ static void rtnetlink_report_change(const struct nlmsghdr *,
                                     struct nlattr *attrs[]);
 static void rtnetlink_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
 rtnetlink_notifier_register(struct rtnetlink_notifier *notifier,
                             rtnetlink_notify_func *cb, void *aux)
@@ -1629,6 +1638,8 @@ rtnetlink_notifier_register(struct rtnetlink_notifier *notifier,
     return 0;
 }
 
+/* Cancels notification on 'notifier', which must have previously been
+ * registered with lxnetdev_notifier_register(). */
 void
 rtnetlink_notifier_unregister(struct rtnetlink_notifier *notifier)
 {
@@ -1639,6 +1650,8 @@ rtnetlink_notifier_unregister(struct rtnetlink_notifier *notifier)
     }
 }
 
+/* Calls all of the registered notifiers, passing along any as-yet-unreported
+ * netdev change events. */
 void
 rtnetlink_notifier_run(void)
 {
@@ -1681,6 +1694,8 @@ rtnetlink_notifier_run(void)
     }
 }
 
+/* Causes poll_block() to wake up when network device change notifications are
+ * ready. */
 void
 rtnetlink_notifier_wait(void)
 {
diff --git a/lib/netdev-linux.h b/lib/netdev-linux.h
index 9c0a2e02f..42ea380a6 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 rtnetlink_change {
     /* Copied from struct nlmsghdr. */
     int nlmsg_type;             /* e.g. RTM_NEWLINK, RTM_DELLINK. */
@@ -34,8 +36,12 @@ struct rtnetlink_change {
     int master_ifindex;         /* Ifindex of datapath master (0 if none). */
 };
 
-typedef void rtnetlink_notify_func(const struct rtnetlink_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 rtnetlink_notify_func(const struct rtnetlink_change *, void *aux);
 
 struct rtnetlink_notifier {
     struct list node;
-- 
2.43.0