From f090079390dd8e1aaea288ec1b69f8e8bb22de1a Mon Sep 17 00:00:00 2001
From: Mark Stapp <mjs@cisco.com>
Date: Fri, 5 Apr 2024 13:14:48 -0400
Subject: [PATCH 1/3] lib: add simple generic version helpers

Add some simple helpers for generic major+minor+sub version
values.

Signed-off-by: Mark Stapp <mjs@cisco.com>
---
 lib/libfrr.c |  9 +++++++++
 lib/libfrr.h | 11 +++++++++++
 2 files changed, 20 insertions(+)

diff --git a/lib/libfrr.c b/lib/libfrr.c
index c5c7e7837a..03025328b7 100644
--- a/lib/libfrr.c
+++ b/lib/libfrr.c
@@ -1450,3 +1450,12 @@ void _libfrr_version(void)
 	write(1, banner, sizeof(banner) - 1);
 	_exit(0);
 }
+
+/* Render simple version tuple to string */
+const char *frr_vers2str(uint32_t version, char *buf, int buflen)
+{
+	snprintf(buf, buflen, "%d.%d.%d", MAJOR_FRRVERSION(version),
+		 MINOR_FRRVERSION(version), SUB_FRRVERSION(version));
+
+	return buf;
+}
diff --git a/lib/libfrr.h b/lib/libfrr.h
index ee436d9f8f..77d70448a9 100644
--- a/lib/libfrr.h
+++ b/lib/libfrr.h
@@ -233,6 +233,17 @@ extern bool frr_is_after_fork;
 
 extern bool debug_memstats_at_exit;
 
+/*
+ * Version numbering: MAJOR (8) | MINOR (16) | SUB (8)
+ */
+#define MAKE_FRRVERSION(maj, min, sub)                                         \
+	((((maj) & 0xff) << 24) | (((min) & 0xffff) << 8) | ((sub) & 0xff))
+#define MAJOR_FRRVERSION(v) (((v) >> 24) & 0xff)
+#define MINOR_FRRVERSION(v) (((v) >> 8) & 0xffff)
+#define SUB_FRRVERSION(v)  ((v) & 0xff)
+
+const char *frr_vers2str(uint32_t version, char *buf, int buflen);
+
 #ifdef __cplusplus
 }
 #endif

From 9f285dd0bc0d95ebaea4ee92ef6ef8ef45649162 Mon Sep 17 00:00:00 2001
From: Mark Stapp <mjs@cisco.com>
Date: Fri, 5 Apr 2024 13:32:08 -0400
Subject: [PATCH 2/3] zebra: add dataplane API version value

Add a version value and accessor API for the zebra dataplane;
plugins can test this to detect API changes.

Signed-off-by: Mark Stapp <mjs@cisco.com>
---
 zebra/zebra_dplane.c | 13 +++++++++++++
 zebra/zebra_dplane.h |  7 +++++++
 2 files changed, 20 insertions(+)

diff --git a/zebra/zebra_dplane.c b/zebra/zebra_dplane.c
index 006ab504ef..06b34da209 100644
--- a/zebra/zebra_dplane.c
+++ b/zebra/zebra_dplane.c
@@ -39,6 +39,13 @@ DEFINE_MTYPE_STATIC(ZEBRA, DP_NS, "DPlane NSes");
 #  define AOK 0
 #endif
 
+/*
+ * Dataplane API version. This must be updated when any incompatible changes
+ * are made. The minor version (at least) should be updated when new APIs
+ * are introduced.
+ */
+static uint32_t zdplane_version = MAKE_FRRVERSION(2, 0, 0);
+
 /* Control for collection of extra interface info with route updates; a plugin
  * can enable the extra info via a dplane api.
  */
@@ -664,6 +671,12 @@ neigh_update_internal(enum dplane_op_e op, const struct interface *ifp,
  * Public APIs
  */
 
+/* Access the dplane API version */
+uint32_t zebra_dplane_get_version(void)
+{
+	return zdplane_version;
+}
+
 /* Obtain thread_master for dataplane thread */
 struct event_loop *dplane_get_thread_master(void)
 {
diff --git a/zebra/zebra_dplane.h b/zebra/zebra_dplane.h
index 2f7d218508..060b1c8b9e 100644
--- a/zebra/zebra_dplane.h
+++ b/zebra/zebra_dplane.h
@@ -24,6 +24,13 @@
 extern "C" {
 #endif
 
+/* Retrieve the dataplane API version number; see libfrr.h to decode major,
+ * minor, sub version values.
+ * Plugins should pay attention to the major version number, at least, to
+ * be able to detect API changes that may not be backward-compatible.
+ */
+uint32_t zebra_dplane_get_version(void);
+
 /* Key netlink info from zebra ns */
 struct zebra_dplane_info {
 	ns_id_t ns_id;

From f8cab9972795d13b9ea5d02af82182ba51327020 Mon Sep 17 00:00:00 2001
From: Mark Stapp <mjs@cisco.com>
Date: Mon, 8 Apr 2024 14:23:58 -0400
Subject: [PATCH 3/3] doc: add doc about the zebra dataplane api version

Add a block to the dev doc about the dataplane api version.

Signed-off-by: Mark Stapp <mjs@cisco.com>
---
 doc/developer/zebra.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/developer/zebra.rst b/doc/developer/zebra.rst
index be2952e71a..482df96267 100644
--- a/doc/developer/zebra.rst
+++ b/doc/developer/zebra.rst
@@ -161,6 +161,21 @@ Zebra Protocol Commands
 
 The definitions of zebra protocol commands can be found at ``lib/zclient.h``.
 
+
+Zebra Dataplane
+===============
+
+The zebra dataplane subsystem provides a framework for FIB
+programming. Zebra uses the dataplane to program the local kernel as
+it makes changes to objects such as IP routes, MPLS LSPs, and
+interface IP addresses. The dataplane runs in its own pthread, in
+order to off-load work from the main zebra pthread.
+
+The zebra dataplane API is versioned; the version number must be
+updated along with API changes. Plugins can test the current version
+number and confirm that they are compatible with the current version.
+
+
 Dataplane batching
 ==================