bgpd,lib: document the table id / instance usage

Document where relevant about the instance overload to table ID so users
know what to expect.

Signed-off-by: Rafael Zalamena <rzalamena@opensourcerouting.org>

3 files changed, 28 insertions, 0 deletions

diff --git a/bgpd/bgp_zebra.c b/bgpd/bgp_zebra.c
index 3d7481f630..179404a2ce 100644
--- a/bgpd/bgp_zebra.c
+++ b/bgpd/bgp_zebra.c
@@ -2043,6 +2043,18 @@ int bgp_redistribute_set(struct bgp *bgp, afi_t afi, int type,
 	/* Return if already redistribute flag is set. */
 	if (instance) {
 		if (type == ZEBRA_ROUTE_TABLE_DIRECT) {
+			/*
+			 * When redistribution type is `table-direct` the
+			 * instance means `table identification`.
+			 *
+			 * `table_id` support 32bit integers, however since
+			 * `instance` is being overloaded to `table_id` it
+			 * will only be possible to use the first 65535
+			 * entries.
+			 *
+			 * Also the ZAPI must also support `int`
+			 * (see `zebra_redistribute_add`).
+			 */
 			struct redist_table_direct table = {
 				.table_id = instance,
 				.vrf_id = bgp->vrf_id,
diff --git a/lib/zclient.c b/lib/zclient.c
index 8fc9addf2f..9f6542eb31 100644
--- a/lib/zclient.c
+++ b/lib/zclient.c
@@ -4774,6 +4774,16 @@ static void zclient_redistribute_table_direct(struct zclient *zclient, vrf_id_t
 void zclient_redistribute(int command, struct zclient *zclient, afi_t afi,
 			  int type, unsigned short instance, vrf_id_t vrf_id)
 {
+	/*
+	 * When asking for table-direct redistribution the parameter
+	 * `instance` has a different meaning: it means table
+	 * identification.
+	 *
+	 * The table identification information is stored in
+	 * `zclient->mi_redist` along with the VRF identification
+	 * information in a pair (different from the usual single protocol
+	 * instance value).
+	 */
 	if (type == ZEBRA_ROUTE_TABLE_DIRECT) {
 		zclient_redistribute_table_direct(zclient, vrf_id, afi, instance, command);
 		return;
diff --git a/lib/zclient.h b/lib/zclient.h
index 35e23ddf63..f3657822b8 100644
--- a/lib/zclient.h
+++ b/lib/zclient.h
@@ -271,6 +271,12 @@ struct redist_proto {
 /**
  * Redistribute table direct instance data structure: keeps the VRF
  * that subscribed to the table ID.
+ *
+ * **NOTE**
+ * `table_id` is an integer because that is what the netlink interface
+ * uses for route attribute RTA_TABLE (32bit int), however the whole
+ * zclient API uses `unsigned short` (and CLI commands) so it will be
+ * limited to the range 1 to 65535.
  */
 struct redist_table_direct {
 	vrf_id_t vrf_id;