Merge pull request #16183 from LabNConsulting/chopps/notif-doc-update

mgmtd: add empty notif xpath map for completeness

Author: ton31337

doc/developer/mgmtd-dev.rst

@@ -317,12 +317,25 @@ Likewise the client should be cleaned up in the daemon cleanup routine.
 Back-End XPATH mappings
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-In order for ``mgmtd`` to direct configuration to your daemon you need to add
+In order for ``mgmtd`` to direct YANG modeled data to your daemon you should add
 some XPATH mappings to ``mgmtd/mgmt_be_adapter.c``. These XPATHs determine which
-configuration changes get sent over the *back-end* interface to your daemon.
-There are 2 arrays to update the first for config support and the second for
-operational state.
-
+YANG modeled data (e.g., config changes) get sent over the *back-end* interface
+to your daemon. There are 4 arrays to possibly update: configuration,
+operational, notification, and RPC. You only need to add entries to the array
+that you require mapping for.
+
+Additionally the back-end client can specify these XPATH mappings when it
+first connects to mgmtd using it's initial ``SUBSCRIBE`` message.
+
+NOTE: the notif array (``be_client_notif_xpaths``), is a slightly different from
+the other 3 types (config, oper and rpc) in that it maps xpaths the back-end
+client wishes to *receive* notifications for, not the ones it may generate.
+Normally a back-end client is generating notifications; however, mgmtd supports
+back-end clients also "subscribing" to receive these notifications as well from
+other back-end clients through notif_xpath maps.
+
+Config Map Example
+""""""""""""""""""
 Below are the strings added for staticd config support:
 
 .. code-block:: c
@@ -342,6 +355,9 @@ Below are the strings added for staticd config support:
     #endif
     };
 
+
+Operational Map Example
+"""""""""""""""""""""""
 Below are the strings added for zebra operational state support (note zebra is
 not conditionalized b/c it should always be present):
 
@@ -358,6 +374,33 @@ not conditionalized b/c it should always be present):
             [MGMTD_BE_CLIENT_ID_ZEBRA] = zebra_oper_xpaths,
     };
 
+
+RPC Map Example
+"""""""""""""""
+Below is the string added for ripd RPC support:
+
+.. code-block:: c
+
+    static const char *const ripd_rpc_xpaths[] = {
+            "/frr-ripd",
+            NULL,
+    };
+
+    static const char *const *be_client_rpc_xpaths[MGMTD_BE_CLIENT_ID_MAX] = {
+    #ifdef HAVE_RIPD
+            [MGMTD_BE_CLIENT_ID_RIPD] = ripd_rpc_xpaths,
+    #endif
+    };
+
+
+Notification Map Example
+""""""""""""""""""""""""
+There are no current back-end daemons that wish to receive other back-end
+notifications so the array is empty. This may change in the future, and of
+course any back-end daemon can utilize the connect (``BeSubscribeReq``) messages
+as well.
+
+
 MGMTD Internals
 ---------------
 

doc/user/mgmtd.rst

@@ -97,13 +97,23 @@ Following are some of the management operations supported:
  - Currently committing configurations from Candidate to Running database
    is only allowed, and not vice versa.
 
+Front-End Native Protobuf API
+"""""""""""""""""""""""""""""
 The exact set of message-based APIs are represented as Google Protobuf
 messages and can be found in the following file distributed with FRR codebase.
 
 .. code-block:: frr
 
    lib/mgmt.proto
 
+Front-End Native (non-protobuf) API
+"""""""""""""""""""""""""""""""""""
+Additionally there exists a "native" API that does not utilize ``protobuf``s
+this native API and the front-end messages and structures it supports are
+documented in the header file ``lib/mgmt_msg_native.h``.
+
+Connecting to MGMTd
+"""""""""""""""""""
 The MGMT daemon implements a MGMT Frontend Server that opens a UNIX
 socket-based IPC channel on the following path to listen for incoming
 connections from all possible Frontend clients:
@@ -124,7 +134,9 @@ specification of this library can be found at:
 
    lib/mgmt_fe_client.h
 
-Following is a list of message types supported on the MGMT Frontend Interface:
+Following is a list of protobuf message types supported on the MGMT Frontend
+Interface:
+
  - SESSION_REQ<Client-Connection-Id, Destroy>
  - SESSION_REPLY<Client-Connection-Id, Destroy, Session-Id>
  - LOCK_DB_REQ <Session-Id, Database-Id>
@@ -139,8 +151,21 @@ Following is a list of message types supported on the MGMT Frontend Interface:
  - COMMIT_CONFIG_REPLY <Session-Id, Source-Db-id, Dest-Db-Id, Status>
  - GET_DATA_REQ <Session-Id, Database-Id, Base-Yang-Xpath>
  - GET_DATA_REPLY <Session-Id, Database-id, Base-Yang-Xpath, Yang-Data-Set>
- - REGISTER_NOTIFY_REQ <Session-Id, Database-Id, Base-Yang-Xpath>
- - DATA_NOTIFY_REQ <Database-Id, Base-Yang-Xpath, Yang-Data-Set>
+
+Following is a list of native messages types supported by the MGMTd Front-End
+API:
+
+ - ERROR (receive) - received in response to any sent native message.
+ - TREE_DATA (receive) - returned data from a datastore
+ - GET_DATA (send) - get a tree of data
+ - NOTIFY (receive) - a notification received from mgmtd
+ - EDIT (send) - edit configuration datastore
+ - EDIT_REPLY (receive) - reply for an edit operation
+ - RPC (send) - sending (invoking) an RPC.
+ - RPC_REPLY (receive) - reply from invoking an RPC
+ - NOTIFY_SELECT (send) - specify the sub-set of notifications the front-end
+   wishes to receive, rather than the default of receiving all.
+
 
 Please refer to the MGMT Frontend Client Developers Reference and Guide
 (coming soon) for more details.

mgmtd/mgmt_be_adapter.c

@@ -155,6 +155,9 @@ static const char *const *be_client_oper_xpaths[MGMTD_BE_CLIENT_ID_MAX] = {
 	[MGMTD_BE_CLIENT_ID_ZEBRA] = zebra_oper_xpaths,
 };
 
+static const char *const *be_client_notif_xpaths[MGMTD_BE_CLIENT_ID_MAX] = {
+};
+
 static const char *const *be_client_rpc_xpaths[MGMTD_BE_CLIENT_ID_MAX] = {
 #ifdef HAVE_RIPD
 	[MGMTD_BE_CLIENT_ID_RIPD] = ripd_rpc_xpaths,
@@ -298,6 +301,13 @@ static void mgmt_be_xpath_map_init(void)
 						   MGMT_BE_XPATH_SUBSCR_TYPE_OPER);
 		}
 
+		/* Initialize the common NOTIF init map */
+		for (init = be_client_notif_xpaths[id]; init && *init; init++) {
+			__dbg(" - NOTIF XPATH: '%s'", *init);
+			mgmt_register_client_xpath(id, *init,
+						   MGMT_BE_XPATH_SUBSCR_TYPE_NOTIF);
+		}
+
 		/* Initialize the common RPC init map */
 		for (init = be_client_rpc_xpaths[id]; init && *init; init++) {
 			__dbg(" - RPC XPATH: '%s'", *init);
@@ -308,6 +318,7 @@ static void mgmt_be_xpath_map_init(void)
 
 	__dbg("Total Cfg XPath Maps: %u", darr_len(be_cfg_xpath_map));
 	__dbg("Total Oper XPath Maps: %u", darr_len(be_oper_xpath_map));
+	__dbg("Total Noitf XPath Maps: %u", darr_len(be_notif_xpath_map));
 	__dbg("Total RPC XPath Maps: %u", darr_len(be_rpc_xpath_map));
 }