diff mbox series

[2/2] doc: handlers: Describe property decompressed-size

Message ID 20200919183010.100367-2-bage@linutronix.de
State Changes Requested
Headers show
Series [1/2] handles: ubivol: add property decompressed-size | expand

Commit Message

Bastian Germann Sept. 19, 2020, 6:30 p.m. UTC 
From: Bastian Germann <bage@linutronix.de>

Move the documentation about "decrypted-size" from the encrypted images doc
to the UBI Volume Handler doc and reference it in the old place.

Extend the description by adding decompressed-size with an example.

Signed-off-by: Bastian Germann <bage@linutronix.de>
---
 doc/source/encrypted_images.rst | 27 ++++-------------------
 doc/source/handlers.rst         | 38 +++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 23 deletions(-)
diff mbox series

Patch

diff --git a/doc/source/encrypted_images.rst b/doc/source/encrypted_images.rst
index e71cdd8..949dabb 100644
--- a/doc/source/encrypted_images.rst
+++ b/doc/source/encrypted_images.rst
@@ -57,30 +57,10 @@  sw-description attribute overrides the key file's IV for one specific image.
 Encryption of UBI volumes
 -------------------------
 
-Due to a limit in the Linux kernel api for UBI volumes, the size reserved to be
-written on disk should be declared before actually write anything.
-Unfortunately, the size of an encrypted image is not know until the complete
-decryption, thus preventing to correctly declare the size of the file to be
-written on disk.
+Due to a limit in the Linux kernel API for UBI volumes, the size reserved to be
+written on disk should be declared before actually writing anything.
 
-For this reason UBI images can declare the special property "decrypted-size" like
-this:
-
-::
-
-	images: ( {
-			filename = "rootfs.ubifs.enc";
-			volume = "rootfs";
-			encrypted = true;
-			ivt = "65D793B87B6724BB27954C7664F15FF3";
-			properties = {decrypted-size = "104857600";}
-		}
-	);
-
-The real size of the decrypted image should be calculated and written to the
-sw-description before assembling the cpio archive.
-In this example, 104857600 is the size of the rootfs after the decryption: the
-encrypted size is by the way larger.
+See the property "decrypted-size" in UBI Volume Handler's documentation.
 
 Example sw-description with Encrypted Image
 -------------------------------------------
@@ -98,6 +78,7 @@  setting.
         			filename = "core-image-full-cmdline-beaglebone.ext3.enc";
         			device = "/dev/mmcblk0p3";
         			encrypted = true;
+				ivt = "65D793B87B6724BB27954C7664F15FF3";
         		}
         	);
         }
diff --git a/doc/source/handlers.rst b/doc/source/handlers.rst
index 30afb46..c487227 100644
--- a/doc/source/handlers.rst
+++ b/doc/source/handlers.rst
@@ -228,6 +228,44 @@  should be used with property ``auto-resize``.
 		}
 	}
 
+size properties
+...............
+Due to a limit in the Linux kernel API for UBI volumes, the size reserved to be
+written on disk should be declared before actually writing anything.
+Unfortunately, the size of an encrypted or compressed image is not known until
+the decryption or decompression finished. This prevents correct declaration of
+the file size to be written on disk.
+
+For this reason UBI images can declare the special properties "decrypted-size"
+or "decompressed-size" like this:
+
+::
+
+	images: ( {
+			filename = "rootfs.ubifs.enc";
+			volume = "rootfs";
+			encrypted = true;
+			properties: {
+				decrypted-size = "104857600";
+			}
+		},
+		{
+			filename = "homefs.ubifs.gz";
+			volume = "homefs";
+			properties: {
+				decompressed-size = "420000000";
+			}
+		}
+	);
+
+The real size of the image should be calculated and written to the
+sw-description before assembling the cpio archive.
+In this example, 104857600 is the size of the rootfs after the decryption: the
+encrypted size is by the way larger. The decompressed size is of the homefs is
+420000000.
+
+The sizes are bytes in decimal notation.
+
 Lua Handlers
 ------------