From: Quentin Young <qlyoung@cumulusnetworks.com>
Date: Wed, 18 Dec 2019 20:58:08 +0000 (-0500)
Subject: lib: document vrf_socket(), vrf_bind()
X-Git-Tag: base_7.3~58^2~1
X-Git-Url: https://git.puffer.fish/?a=commitdiff_plain;h=79a80af8b4dd59af84f4cc9a9a7488f0e9adb6e7;p=mirror%2Ffrr.git

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 2411cc3111..0a01b2159e 100644
--- 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 ca253e58a3..1d87576f78 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 */