michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: services: device_mgmt: smp_groups: Clarify img_mgmt upload

Browse source 
Clarifies the details in the upload section of img_mgmt for MCUmgr
to better describe when fields should be sent, including a note
when a server responds with offset of 0.

Signed-off-by: Jamie McCrae <jamie.mccrae@nordicsemi.no>
This commit is contained in:
Jamie McCrae 2023-07-28 09:51:52 +01:00 • committed by Carles Cufí
commit 8a2e768ff7
1 changed files with 35 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

66
doc/services/device_mgmt/smp_groups/smp_group_1.rst
View file

@ -269,7 +269,7 @@ CBOR data of request:
(str,opt)"len" : (uint) (str,opt)"len" : (uint)
(str)"off" : (uint) (str)"off" : (uint)
(str,opt)"sha" : (byte str) (str,opt)"sha" : (byte str)
(str,opt)"data" : (byte str) (str)"data" : (byte str)
(str,opt)"upgrade" : (bool) (str,opt)"upgrade" : (bool)
} }
@ -278,41 +278,45 @@ where:
.. table:: .. table::
:align: center :align: center
+-----------------------+---------------------------------------------------+ +-----------+--------------------------------------------------------------------------------+
| "image" | optional image number, it does not have to appear | | "image" | optional image number, it does not have to appear in request at all, in which |
| | in request at all, in which case it is assumed to | | | case it is assumed to be 0. Should only be present when "off" is 0. |
| | be 0; only request with "off" 0 can contain | +-----------+--------------------------------------------------------------------------------+
| | image number | | "len" | optional length of an image. Must appear when "off" is 0. |
+-----------------------+---------------------------------------------------+ +-----------+--------------------------------------------------------------------------------+
| "len" | optional length of an image, it only appears in | | "off" | offset of image chunk the request carries. |
| | the first packet of request, where "off" is 0 | +-----------+--------------------------------------------------------------------------------+
+-----------------------+---------------------------------------------------+ | "sha" | SHA256 hash of an upload; this is used to identify an upload session (e.g. to |
| "off" | offset of image chunk the request carries | | | allow MCUmgr to continue a broken session), and for image verification |
+-----------------------+---------------------------------------------------+ | | purposes. This must be a full SHA256 hash of the whole image being uploaded, |
| "sha" | SHA256 hash of an upload; this is used to | | | or not included if the hash is not available (in which case, upload session |
| | identify an upload session (e.g. to allow MCUmgr | | | continuation and image verification functionality will be unavailable). Should |
| | to continue a broken session), and for image | | | only be present when "off" is 0. |
| | verification purposes. This must be a full SHA256 | +-----------+--------------------------------------------------------------------------------+
| | hash of the whole image being uploaded, or not | | "data" | image data to write at provided offset. |
| | included if the hash is not available (in which | +-----------+--------------------------------------------------------------------------------+
| | case, upload session continuation and image | | "upgrade" | optional flag that states that only upgrade should be allowed, so if the |
| | verification functionality will be unavailable). | | | version of uploaded software is not higher then already on a device, the image |
| | Should only be present if "off" is zero. | | | upload will be rejected. Zephyr compares major, minor and revision (x.y.z) by |
+-----------------------+---------------------------------------------------+ | | default unless |
| "data" | optional image data | | | :kconfig:option:`CONFIG_MCUMGR_GRP_IMG_VERSION_CMP_USE_BUILD_NUMBER` is set, |
+-----------------------+---------------------------------------------------+ | | whereby it will compare build numbers too. Should only be present when "off" |
| "upgrade" | optional flag that states that only upgrade | | | is 0. |
| | should be allowed, so if the version of uploaded | +-----------+--------------------------------------------------------------------------------+
| | software is not higher then already on a device, |
| | the image upload will be rejected. |
| | Zephyr only compares major, minor and revision |
| | (x.y.z). |
+-----------------------+---------------------------------------------------+
.. note:: .. note::
There is no field representing size of chunk that is carried as "data" because There is no field representing size of chunk that is carried as "data" because
that information is embedded within "data" field itself. that information is embedded within "data" field itself.
.. note::
It is possible that a server will respond to an upload with "off" of 0, this
may happen if an upload on another transport (or outside of MCUmgr entirely)
is started, if the device has rebooted or if a packet has been lost. If this
happens, a client must re-send all the required and optional fields that it
sent in the original first packet so that the upload state can be re-created
by the server. If the original fields are not included, the upload will be
unable to continue.
The MCUmgr library uses "sha" field to tag ongoing update session, to be able The MCUmgr library uses "sha" field to tag ongoing update session, to be able
to continue it in case when it gets broken, and for upload verification to continue it in case when it gets broken, and for upload verification
purposes. purposes.