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>

1 files changed, 24 insertions, 1 deletions

diff --git a/lib/vrf.h b/lib/vrf.h
index ca253e58a..1d87576f7 100644
--- 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 */