mgmt: mcumgr: grp: img_mgmt: Add slot info command

doc/releases/release-notes-4.0.rst

@@ -345,6 +345,8 @@ Libraries / Subsystems
     * Added support for custom os mgmt bootloader info responses using notification hooks, this
       can be enabled witbh :kconfig:option:`CONFIG_MCUMGR_GRP_OS_BOOTLOADER_INFO_HOOK`, the data
       structure is :c:struct:`os_mgmt_bootloader_info_data`.
+    * Added support for img mgmt slot info command, which allows for listing information on
+      images and slots on the device.
 
 * Logging
 

doc/services/device_mgmt/smp_groups/smp_group_1.rst

@@ -26,6 +26,8 @@ Application/software image management group defines following commands:
     +-------------------+-----------------------------------------------+
     | ``5``             | Image erase                                   |
     +-------------------+-----------------------------------------------+
+    | ``6``             | Slot info                                     |
+    +-------------------+-----------------------------------------------+
 
 Notion of "slots" and "images" in Zephyr
 ****************************************
@@ -516,3 +518,115 @@ where:
     Response from Zephyr running device may have "rc" value of
     :c:enumerator:`MGMT_ERR_EBADSTATE`, which means that the secondary
     image has been marked for next boot already and may not be erased.
+
+Slot info
+*********
+
+The command is used for fetching information on slots that are available. This command can be
+enabled with :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_SLOT_INFO`.
+
+Slot info request
+=================
+
+Slot info request header fields:
+
+.. table::
+    :align: center
+
+    +--------+--------------+----------------+
+    | ``OP`` | ``Group ID`` | ``Command ID`` |
+    +========+==============+================+
+    | ``0``  | ``1``        |  ``6``         |
+    +--------+--------------+----------------+
+
+The command sends an empty CBOR map as data.
+
+Slot info response
+==================
+
+Slot info response header fields:
+
+.. table::
+    :align: center
+
+    +--------+--------------+----------------+
+    | ``OP`` | ``Group ID`` | ``Command ID`` |
+    +========+==============+================+
+    | ``1``  | ``1``        |  ``6``         |
+    +--------+--------------+----------------+
+
+CBOR data of successful response:
+
+.. code-block:: none
+
+    {
+        (str)"images" : [
+            {
+                (str)"image"                        : (uint)
+                (str)"slots" : [
+                    {
+                        (str)"slot"                 : (uint)
+                        (str)"size"                 : (uint)
+                        (str,opt)"upload_image_id"  : (uint)
+                    }
+                    ...
+                ]
+                (str,opt)"max_image_size"           : (uint)
+            }
+            ...
+        ]
+    }
+
+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 (and non-group SMP version 2)
+
+      .. code-block:: none
+
+          {
+              (str)"rc"       : (int)
+          }
+
+where:
+
+.. table::
+    :align: center
+
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "image"           | the image number being enumerated.                                                         |
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "slot"            | the slot inside the image being enumerated (note: this will be 0 or 1, it is the slot of   |
+    |                   | the image not the physical slot number).                                                   |
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "size"            | the size of the slot.                                                                      |
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "upload_image_id" | optional field (only present if :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_DIRECT_UPLOAD` is   |
+    |                   | enabled to allow direct image uploads) which specifies the image ID that can be used by    |
+    |                   | external tools to upload an image to that slot.                                            |
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "max_image_size"  | optional field (only present if :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_TOO_LARGE_SYSBUILD` |
+    |                   | or :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_TOO_LARGE_BOOTLOADER_INFO` are enabled) which    |
+    |                   | specifies the maximum size of an application that can be uploaded to that image number.    |
+    +-------------------+--------------------------------------------------------------------------------------------+
+    | "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 ifnon-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.                                                |
+    +-------------------+--------------------------------------------------------------------------------------------+

include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt.h

@@ -1,6 +1,6 @@
 /*
  * Copyright (c) 2018-2021 mcumgr authors
- * Copyright (c) 2022-2023 Nordic Semiconductor ASA
+ * Copyright (c) 2022-2024 Nordic Semiconductor ASA
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -56,7 +56,8 @@
 #define IMG_MGMT_ID_CORELIST	3
 #define IMG_MGMT_ID_CORELOAD	4
 #define IMG_MGMT_ID_ERASE	5
+#define IMG_MGMT_ID_SLOT_INFO	6
 
 /**
  * Command result codes for image management group.
  */

include/zephyr/mgmt/mcumgr/grp/img_mgmt/img_mgmt_callbacks.h

@@ -55,6 +55,44 @@ struct img_mgmt_state_slot_encode {
 	const int flags;
 };
 
+/**
+ * Structure provided in the #MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_IMAGE notification callback: This
+ * callback function is called once per image when the slot info command is used, it can be used
+ * to return additional information/fields in the response.
+ */
+struct img_mgmt_slot_info_image {
+	/** The image that is currently being enumerated. */
+	const uint8_t image;
+
+	/**
+	 * The zcbor encoder which is currently being used to output information, additional fields
+	 * can be added using this.
+	 */
+	zcbor_state_t *zse;
+};
+
+/**
+ * Structure provided in the #MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_SLOT notification callback: This
+ * callback function is called once per slot per image when the slot info command is used, it can
+ * be used to return additional information/fields in the response.
+ */
+struct img_mgmt_slot_info_slot {
+	/** The image that is currently being enumerated. */
+	const uint8_t image;
+
+	/** The slot that is currently being enumerated. */
+	const uint8_t slot;
+
+	/** Flash area of the slot that is current being enumerated. */
+	const struct flash_area *fa;
+
+	/**
+	 * The zcbor encoder which is currently being used to output information, additional fields
+	 * can be added using this.
+	 */
+	zcbor_state_t *zse;
+};
+
 /**
  * @}
  */

include/zephyr/mgmt/mcumgr/mgmt/callbacks.h

@@ -188,6 +188,12 @@
 	/** Callback when an image slot's state is encoded for a response. */
 	MGMT_EVT_OP_IMG_MGMT_IMAGE_SLOT_STATE		= MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 6),
 
+	/** Callback when an slot list command outputs fields for an image. */
+	MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_IMAGE		= MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 7),
+
+	/** Callback when an slot list command outputs fields for a slot of an image. */
+	MGMT_EVT_OP_IMG_MGMT_SLOT_INFO_SLOT		= MGMT_DEF_EVT_OP_ID(MGMT_EVT_GRP_IMG, 8),
+
 	/** Used to enable all img_mgmt_group events. */
 	MGMT_EVT_OP_IMG_MGMT_ALL			= MGMT_DEF_EVT_OP_ALL(MGMT_EVT_GRP_IMG),
 };

subsys/mgmt/mcumgr/grp/img_mgmt/Kconfig

@@ -201,6 +201,20 @@ config MCUMGR_GRP_IMG_IMAGE_SLOT_STATE_STATES
 	  The value does not affect memory allocation, it is used by zcbor
 	  to figure out how to encode map depending on its predicted size.
 
+config MCUMGR_GRP_IMG_SLOT_INFO
+	bool "Slot info"
+	default y if MCUMGR_GRP_IMG_UPDATABLE_IMAGE_NUMBER > 1
+	help
+	  This will enable the slot information function which will return information about all
+	  images and slots that the application can see.
+
+config MCUMGR_GRP_IMG_SLOT_INFO_HOOKS
+	bool "Slot info hooks"
+	depends on MCUMGR_GRP_IMG_SLOT_INFO && MCUMGR_MGMT_NOTIFICATION_HOOKS
+	help
+	  This will enable the slot info function hooks which can be used to add additional
+	  information to responses.
+
 module = MCUMGR_GRP_IMG
 module-str = mcumgr_grp_img
 source "subsys/logging/Kconfig.template.log_config"