diff mbox series

docs: Document cpio format flavor

Message ID 1F19C250-B615-4F2C-998C-B0AEEF1A37DF@siemens.com
State Accepted
Headers show
Series docs: Document cpio format flavor | expand

Commit Message

Storm, Christian May 23, 2024, 4:26 p.m. UTC 
Document the cpio file format flavor used by SWUpdate.

Signed-off-by: Christian Storm <christian.storm@siemens.com>
---
 doc/source/swupdate.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)
diff mbox series

Patch

diff --git a/doc/source/swupdate.rst b/doc/source/swupdate.rst
index d444a409..34a61d7e 100644
--- a/doc/source/swupdate.rst
+++ b/doc/source/swupdate.rst
@@ -820,6 +820,31 @@  risk, we are not modifying original environment block. Variables are written
 into temporary file and after successful operation rename instruction is
 called.
 
+
+Image File Format
+=================
+
+SWUpdate uses cpio as image file format because it is a simple,
+well-established, and streamable format. More specifically, the
+*New ASCII* format (header magic number ``070701``) and the
+*New CRC* format (header magic number ``070702``) are supported.
+Both formats are essentially equivalent with the New CRC format additionally
+having set the cpio header field ``check`` to the least-significant 32 bits of
+the sum of all (unsigned) data bytes. This checksum is verified by SWUpdate.
+If this verification fails, SWUpdate yields an error like the following:
+
+::
+
+	Checksum WRONG ! Computed 0xfa11ed00, it should be 0xffffffff
+
+Note that there's artifact sha256 verification available
+(see ``CONFIG_HASH_VERIFY``) which is recommended over relying
+on cpio's checksum facility.
+
+For both cpio formats, the New ASCII as well as the New CRC format, the
+cpio file size is limited to 32 Bit, i.e., 4 GB.
+
+
 Building a single image
 =======================