lib: document vrf_socket(), vrf_bind()

These two don't really do what you might expect, document them

Signed-off-by: Quentin Young <qlyoung@cumulusnetworks.com>

diff --git a/lib/vrf.c b/lib/vrf.c
index 2411cc31118d6820274366de314f676e420eef01..0a01b2159e32c7e052d706e12f2dc90eb88d357d 100644 (file)
--- a/lib/vrf.c
+++ b/lib/vrf.c
@@ -555,7 +555,6 @@ void vrf_terminate(void)
        }
 }
 
-/* Create a socket for the VRF. */
 int vrf_socket(int domain, int type, int protocol, vrf_id_t vrf_id,
               const char *interfacename)
 {

diff --git a/lib/vrf.h b/lib/vrf.h
index ca253e58a3618c2c83cee703d7ba26649998a9f7..1d87576f78818c2f10c8ebdda48c3189ff4ac123 100644 (file)
--- a/lib/vrf.h
+++ b/lib/vrf.h
@@ -218,13 +218,36 @@ extern void vrf_terminate(void);
  * or call network operations
  */
 
-/* Create a socket serving for the given VRF */
+/*
+ * Create a new socket associated with a VRF.
+ *
+ * This is a wrapper that ensures correct behavior when using namespace VRFs.
+ * In the namespace case, the socket is created within the namespace. In the
+ * non-namespace case, this is equivalent to socket().
+ *
+ * If name is provided, this is provided to vrf_bind() to bind the socket to
+ * the VRF. This is only relevant when using VRF-lite.
+ *
+ * Summary:
+ * - Namespace: pass vrf_id but not name
+ * - VRF-lite: pass vrf_id and name of VRF device to bind to
+ * - VRF-lite, no binding: pass vrf_id but not name, or just use socket()
+ */
 extern int vrf_socket(int domain, int type, int protocol, vrf_id_t vrf_id,
                      const char *name);
 
 extern int vrf_sockunion_socket(const union sockunion *su, vrf_id_t vrf_id,
                                const char *name);
 
+/*
+ * Binds a socket to a VRF device.
+ *
+ * If name is null, the socket is not bound, irrespective of any other
+ * arguments.
+ *
+ * name should be the name of the VRF device. vrf_id should be the
+ * corresponding vrf_id (the ifindex of the device).
+ */
 extern int vrf_bind(vrf_id_t vrf_id, int fd, const char *name);
 
 /* VRF ioctl operations */