doc: mcumgr: smp_group_63: Add zephyr mgmt group documentation

Adds documentation describing the MCUmgr Zephyr management group and supported commands Signed-off-by: Jamie McCrae <[email protected]>
zephyrproject-rtos · Nov 1, 2023 · 2107122 · 2107122
1 parent 563f5a7
commit 2107122
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 1 deletion.
diff --git a/doc/services/device_mgmt/index.rst b/doc/services/device_mgmt/index.rst
@@ -28,3 +28,4 @@ SMP Groups
     smp_groups/smp_group_3.rst
     smp_groups/smp_group_8.rst
     smp_groups/smp_group_9.rst
+    smp_groups/smp_group_63.rst
diff --git a/doc/services/device_mgmt/smp_groups/smp_group_63.rst b/doc/services/device_mgmt/smp_groups/smp_group_63.rst
@@ -0,0 +1,92 @@
+.. _mcumgr_smp_group_63:
+
+Zephyr Management Group
+#######################
+
+Zephyr management group defines the following commands:
+
+.. table::
+    :align: center
+
+    +----------------+------------------------------+
+    | ``Command ID`` | Command description          |
+    +================+==============================+
+    | ``0``          | Erase storage                |
+    +----------------+------------------------------+
+
+Erase storage command
+*********************
+
+Erase storage command allows clearing the ``storage_partition`` flash partition on a device,
+generally this is used when switching to a new application build if the application uses storage
+that should be cleared (application dependent).
+
+Erase storage request
+=====================
+
+Erase storage request header fields:
+
+.. table::
+    :align: center
+
+    +--------+--------------+----------------+
+    | ``OP`` | ``Group ID`` | ``Command ID`` |
+    +========+==============+================+
+    | ``2``  | ``63``       | ``0``          |
+    +--------+--------------+----------------+
+
+The command sends sends empty CBOR map as data.
+
+Erase storage response
+======================
+
+Read setting response header fields:
+
+.. table::
+    :align: center
+
+    +--------+--------------+----------------+
+    | ``OP`` | ``Group ID`` | ``Command ID`` |
+    +========+==============+================+
+    | ``3``  | ``63``       | ``0``          |
+    +--------+--------------+----------------+
+
+The command sends an empty CBOR map as data if successful. In case of error the CBOR data takes
+the form:
+
+.. tabs::
+
+   .. group-tab:: SMP version 2
+
+      .. code-block:: none
+
+          {
+              (str)"err" : {
+                  (str)"group"    : (uint)
+                  (str)"rc"       : (uint)
+              }
+          }
+
+   .. group-tab:: SMP version 1
+
+      .. code-block:: none
+
+          {
+              (str)"rc"       : (int)
+          }
+
+where:
+
+.. table::
+    :align: center
+
+    +------------------+-------------------------------------------------------------------------+
+    | "err" -> "group" | :c:enum:`mcumgr_group_t` group of the group-based error code. Only      |
+    |                  | appears if an error is returned when using SMP version 2.               |
+    +------------------+-------------------------------------------------------------------------+
+    | "err" -> "rc"    | contains the index of the group-based error code. Only appears if       |
+    |                  | non-zero (error condition) when using SMP version 2.                    |
+    +------------------+-------------------------------------------------------------------------+
+    | "rc"             | :c:enum:`mcumgr_err_t` only appears if non-zero (error condition) when  |
+    |                  | using SMP version 1 or for SMP errors when using SMP version 2.         |
+    +------------------+-------------------------------------------------------------------------+
diff --git a/doc/services/device_mgmt/smp_protocol.rst b/doc/services/device_mgmt/smp_protocol.rst
@@ -141,7 +141,7 @@ groups. The following table presents a list of common groups:
     +---------------+-----------------------------------------------+
     | ``9``         | :ref:`mcumgr_smp_group_9`                     |
     +---------------+-----------------------------------------------+
-    | ``63``        | Zephyr specific basic commands group          |
+    | ``63``        | :ref:`mcumgr_smp_group_63`                    |
     +---------------+-----------------------------------------------+
     | ``64``        | This is the base group for defining           |
     |               | an application specific management groups.    |