michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: guides: device_mgmt: smp: fs: Add hash/checksum/status details

Browse source 
This adds documentation which explains fs mcumgr commands for the status
and hash/checksum commands.

Signed-off-by: Jamie McCrae <jamie.mccrae@lairdconnect.com>
This commit is contained in:
Jamie McCrae 2022-03-21 17:05:42 +00:00 • committed by Carles Cufí
commit 13c00fb96d
1 changed files with 213 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

213
doc/services/device_mgmt/smp_groups/smp_group_8.rst
View file

@ -16,6 +16,10 @@ File management group defines following commands:
+===================+===============================================+
| ``0`` | File download/upload |
+-------------------+-----------------------------------------------+
| ``1`` | File status |
+-------------------+-----------------------------------------------+
| ``2`` | File hash/checksum |
+-------------------+-----------------------------------------------+
File download
*************
@ -216,3 +220,212 @@ where:
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` |
+-----------------------+---------------------------------------------------+
File status
***********
Command allows to retrieve status of an existing file from specified path
of a target device.
File status request
===================
File status request header:
.. table::
:align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``0`` | ``8`` | ``1`` |
+--------+--------------+----------------+
CBOR data of request:
.. code-block:: none
{
(str)"name" : (str)
}
where:
.. table::
:align: center
+-----------------------+---------------------------------------------------+
| "name" | absolute path to a file |
+-----------------------+---------------------------------------------------+
File status response
====================
File status response header:
.. table::
:align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``1`` | ``8`` | ``1`` |
+--------+--------------+----------------+
CBOR data of successful response:
.. code-block:: none
{
(str)"len" : (uint)
}
In case of error the CBOR data takes form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
.. table::
:align: center
+-----------------------+---------------------------------------------------+
| "len" | length of file (in bytes) |
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` (only |
| | present if an error occurred) |
+-----------------------+---------------------------------------------------+
In case when "rc" is not 0, success, the other fields will not appear.
File hash/checksum
******************
Command allows to generate a hash/checksum of an existing file at a specified
path on a target device. Note that kernel heap memory is required for buffers to
be allocated for this to function, and large stack memory buffers are required
for generation of the output hash/checksum.
File hash/checksum request
==========================
File hash/checksum request header:
.. table::
:align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``0`` | ``8`` | ``2`` |
+--------+--------------+----------------+
CBOR data of request:
.. code-block:: none
{
(str)"name" : (str)
(str,opt)"type" : (str)
(str,opt)"off" : (uint)
(str,opt)"len" : (uint)
}
where:
.. table::
:align: center
+-----------------------+---------------------------------------------------+
| "name" | absolute path to a file |
+-----------------------+---------------------------------------------------+
| "type" | type of hash/checksum to perform |
| | :ref:`mcumgr_group_8_hash_checksum_types` or omit |
| | to use default |
+-----------------------+---------------------------------------------------+
| "off" | offset to start hash/checksum calculation at |
| | (optional, 0 if not provided) |
+-----------------------+---------------------------------------------------+
| "len" | maximum length of data to read from file to |
| | generate hash/checksum with (optional, full file |
| | size if not provided) |
+-----------------------+---------------------------------------------------+
.. _mcumgr_group_8_hash_checksum_types:
Hash/checksum types
===================
.. table::
:align: center
+-------------+--------------------------------------+-------------+--------------+
| String name | Hash/checksum | Byte string | Size (bytes) |
+=============+======================================+=============+==============+
| ``crc32`` | IEEE CRC32 checksum | No | 4 |
+-------------+--------------------------------------+-------------+--------------+
| ``sha256`` | SHA256 (Secure Hash Algorithm) | Yes | 32 |
+-------------+--------------------------------------+-------------+--------------+
Note that the default type will be crc32 if it is enabled, or sha256 if crc32 is
not enabled.
File hash/checksum response
===========================
File hash/checksum response header:
.. table::
:align: center
+--------+--------------+----------------+
| ``OP`` | ``Group ID`` | ``Command ID`` |
+========+==============+================+
| ``1`` | ``8`` | ``2`` |
+--------+--------------+----------------+
CBOR data of successful response:
.. code-block:: none
{
(str)"type" : (str)
(str,opt)"off" : (uint)
(str)"len" : (uint)
(str)"output" : (uint or bstr)
}
In case of error the CBOR data takes form:
.. code-block:: none
{
(str)"rc" : (int)
}
where:
.. table::
:align: center
+-----------------------+---------------------------------------------------+
| "rc" | :ref:`mcumgr_smp_protocol_status_codes` (only |
| | present if an error occurred) |
+-----------------------+---------------------------------------------------+
| "type" | type of hash/checksum that was performed |
| | :ref:`mcumgr_group_8_hash_checksum_types` |
+-----------------------+---------------------------------------------------+
| "off" | offset that hash/checksum calculation started at |
| | (only present if off is not 0) |
+-----------------------+---------------------------------------------------+
| "len" | length of input data used for hash/checksum |
| | generation (in bytes) |
+-----------------------+---------------------------------------------------+
| "output" | output hash/checksum |
+-----------------------+---------------------------------------------------+
In case when "rc" is not 0, success, the other fields will not appear.