otamaker: Document the pre_checksum property

Signed-off-by: Phil Elwell <phil@raspberrypi.com>

Author: pelwell

otamaker/README.md

@@ -59,6 +59,9 @@ artefact:
   device_type: rpi5
 
   payloads:
+  - name: preinstall
+    type: script
+    pre_checksum: yes
   - name: boot          # boot.sparse
     type: image-sparse
   - name: system        # system.sparse
@@ -69,7 +72,7 @@ artefact:
     type: script
 ```
 
-Any fields and payload types which aren't recognised are ignored. However, an error is returned if an update doesn't either write to at least one filesystem or include a script.
+Any fields which aren't recognised are ignored. However, an error is returned if an update doesn't either write to at least one filesystem or include a script.
 
 N.B. Although the contents file is structured as a YAML document, only a simple subset of the YAML standard is recognised. It is recommended that you stick to the structure above - anything clever is likely to fail.
 
@@ -87,6 +90,8 @@ The following payload types are recognised:
 
 Comments immediately after (and on the same line as) the `name` field are interpreted by otamaker as a path to the source file. These comments are removed when the final archive is created.
 
+The `pre_checksum` boolean field controls when the payload is processed: if `yes`, the payload is written or executed as the artefact is being downloaded, and if `no` the processing is deferred until the end of the download when the checksum/hash of the artefact has been verified. Using pre-checksum payloads saves time and temporary storage, important for large image payloads, but they do bypass the integrity check, so are best used for pre-install checks and A/B slot updates where rollback is easy. Note that the default value for `pre_checksum` is `yes` for image payloads, and `no` otherwise.
+
 **Scripts**
 
 It is expected that executable payloads will be written in one of the many scripting languages - Bourne shell, Perl, Python 3, etc. - because they are largely independent of the device architecture, but it could be any program that can be run on the target device. For interpreted languages this requires that the interpreter and any associated library modules are already installed on the target. It is also necessary to use a standard "shebang" (`#!/path/to/...`) header, so the target knows how to run it. Either way, executable payloads are referred to as scripts from now on.