From 5546fb1bfbdde2403384ee85f64136ddea8b75b0 Mon Sep 17 00:00:00 2001
From: Pushpasis Sarkar <pushpasis.frr@gmail.com>
Date: Wed, 13 Sep 2023 23:47:20 -0700
Subject: [PATCH] doc: Update MGMTd documentation

This commit updates the existing MGMTd user and developer documentations
with details regarding the new support for retrieving operational
data via the MGMT Front-end interface.

Signed-off-by: Pushpasis Sarkar <pushpasis@gmail.com>
---
 doc/developer/mgmtd-dev.rst | 53 +++++++++++++++++++++++++++++++++++++
 doc/user/mgmtd.rst          | 20 ++++++++------
 2 files changed, 65 insertions(+), 8 deletions(-)

diff --git a/doc/developer/mgmtd-dev.rst b/doc/developer/mgmtd-dev.rst
index 9839aa8b6c82..688822207064 100644
--- a/doc/developer/mgmtd-dev.rst
+++ b/doc/developer/mgmtd-dev.rst
@@ -202,6 +202,59 @@ Below are the strings added for staticd support:
    #endif
    };
 
+The abobe example adds 'staticd' as a configuration validator for certain xpaths
+under the overall data subtree in 'running' and 'candidate' datastores.
+However, sometimes daemons may also need to provide operational data and state
+via the MGMT frontend interface. Below is an example how the zebra daemon
+can add support for retrieveing oprational data for the data subtree it
+represents under the entire data tree in the operational datastore. Please note
+that zebra here only takes responsibility of providing real-time operational
+values of the dpecified data portions,. It does not accept any responsibility
+of validating any data under these data portions, by specifying only 
+'MGMT_SUBSCR_OPER_OWN' for the '.subsribed' value for the corresponding Xpath
+map entry.
+
+.. code-block:: c
+
+    static struct mgmt_be_client_xpath zebra_xpaths[] = {
+        {
+            .xpath = "/frr-zebra:zebra/*",
+            .subscribed = MGMT_SUBSCR_OPER_OWN,
+        },
+        {
+            .xpath = "/frr-vrf:lib/vrf[name='*']/frr-zebra:zebra/*",
+            .subscribed = MGMT_SUBSCR_OPER_OWN,
+        },
+    };
+
+    static struct mgmt_be_client_xpath_map
+        mgmt_client_xpaths[MGMTD_BE_CLIENT_ID_MAX] = {
+            ...
+            [MGMTD_BE_CLIENT_ID_ZEBRA] = {zebra_xpaths,
+                            array_size(zebra_xpaths)},
+            ...
+    };
+
+However a daemon can certainly support both accepting configurational
+values for a data portion (via one of the config datastsores), as well as
+providing the real-time operational value of the same data portion
+(via the 'operational' datastore). In such case it should combine both
+'MGMT_SUBSCR_VALIDATE_CFG' and 'MGMT_SUBSCR_OPER_OWN' values for the 
+'.subscribed' attribute in the corresponding Xpath map entry. Below is
+a variation of the zebra Xpath mappings given above that combines both.
+
+.. code-block:: c
+
+    static struct mgmt_be_client_xpath zebra_xpaths[] = {
+        {
+            .xpath = "/frr-zebra:zebra/*",
+            .subscribed = MGMT_SUBSCR_VALIDATE_CFG | MGMT_SUBSCR_OPER_OWN,
+        },
+        {
+            .xpath = "/frr-vrf:lib/vrf[name='*']/frr-zebra:zebra/*",
+            .subscribed = MGMT_SUBSCR_OPER_OWN,
+        },
+    };
 
 MGMTD Internals
 ^^^^^^^^^^^^^^^
diff --git a/doc/user/mgmtd.rst b/doc/user/mgmtd.rst
index 737eb57c85bc..b37ccb8129ad 100644
--- a/doc/user/mgmtd.rst
+++ b/doc/user/mgmtd.rst
@@ -347,19 +347,23 @@ MGMT Show commands
 .. clicmd:: show mgmt get-config [candidate|running] XPATH
 
     This command uses the GET_CONFIG operation over the MGMT Frontend interface and
-    returns the xpaths and values of the nodes of the subtree pointed by the <xpath>.
+    returns the xpaths and values of the nodes of the subtree pointed by the <xpath>
+    from the specifed datastore. Currenlty only supported values for datastore are
+    'candidate' and 'running'.
 
-.. clicmd:: show mgmt get-data [candidate|operation|running] XPATH
+.. clicmd:: show mgmt get-data operational XPATH
 
     This command uses the GET_DATA operation over the MGMT Frontend interface and
-    returns the xpaths and values of the nodes of the subtree pointed by the <xpath>.
-    Currenlty supported values for 'candidate' and 'running' only
-    ('operational' shall be supported in future soon).
+    returns the xpaths and values of the nodes of the subtree pointed by the <xpath>
+    from a specified datastore. Currenlty only supported values for datastore is
+    'operational'. GET-DATA operation on 'running' and 'candidate' are not allowed
+    (use the 'show mgmt get-config [candidate|running]' instead).
 
-.. clicmd:: show mgmt database-contents [candidate|operation|running] [xpath WORD] [file WORD] json|xml
+.. clicmd:: show mgmt database-contents [candidate|running] [xpath WORD] [file WORD] json|xml
 
-    This command dumps the subtree pointed by the xpath in JSON or XML format. If filepath is
-    not present then the tree will be printed on the shell.
+    This command dumps the subtree pointed by the xpath from a specifed datastore
+    in JSON or XML format. If filepath is not present then the tree will be printed on the
+    shell. Currenlty only supported values for datastore are 'candidate' and 'running'.
 
 .. clicmd:: show mgmt commit-history