Update imgtool documentation

Signed-off-by: Fabio Utzig <utzig@apache.org>

docs/imgtool.md

@@ -50,23 +50,25 @@ into the key file.
 Image signing takes an image in binary or Intel Hex format intended for Slot 0
 and adds a header and trailer that the bootloader is expecting:
 
-    usage: imgtool.py sign [-h] -k filename --align ALIGN -v VERSION -H
+    Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE
-                           HEADER_SIZE [--pad PAD] [--rsa-pkcs1-15]
+
-                           infile outfile
+      Create a signed or unsigned image
-    
+
-    positional arguments:
+    Options:
-      infile
+      -k, --key filename
-      outfile
+      --align [1|2|4|8]          [required]
-    
+      -v, --version TEXT         [required]
-    optional arguments:
+      -H, --header-size INTEGER  [required]
-      -h, --help            show this help message and exit
+      --pad-header               Add `--header-size` zeroed bytes at the beginning
-      -k filename, --key filename
+                                 of the image
-      --align ALIGN
+      -S, --slot-size INTEGER    Size of the slot where the image will be written
-      -v VERSION, --version VERSION
+                                 [required]
-      -H HEADER_SIZE, --header-size HEADER_SIZE
+      --pad                      Pad image to --slot-size bytes, adding trailer
-      --included-header     Image has gap for header
+                                 magic
-      --pad PAD             Pad image to this many bytes, adding trailer magic
+      -M, --max-sectors INTEGER  When padding allow for this amount of sectors
-      --rsa-pkcs1-15        Use old PKCS#1 v1.5 signature algorithm
+                                 (defaults to 128)
+      --overwrite-only           Use overwrite-only instead of swap upgrades
+      -h, --help                 Show this message and exit.
 
 The main arguments given are the key file generated above, a version
 field to place in the header (1.2.3 for example), the alignment of the
@@ -74,16 +76,16 @@ flash device in question, and the header size.
 
 The header size depends on the operating system and the particular
 flash device.  For Zephyr, it will be configured as part of the build,
-and will be a small power of two.  By default, the header will be
+and will be a small power of two.  By default, the Zephyr build system will
-prepended to the image.  If `--included-header` is given, the image
+already prepended a zeroed header to the image.  If another build system is
-must start with header-size bytes of zeros, and the header will be
+in use that does not automatically add this zeroed header, `--pad-header` can
-overwritten over these bytes.
+be passed and the `--header-size` will be added by imgtool.
+
+The `--slot-size` argument is required and used to check that the firmware
+does not overflow into the swap status area (metadata). If swap upgrades are
+not being used, `--overwrite-only` can be passed to avoid adding the swap
+status area size when calculating overflow.
 
 The optional --pad argument will place a trailer on the image that
 indicates that the image should be considered an upgrade.  Writing
 this image in slot 1 will then cause the bootloader to upgrade to it.
-
-Lastly, the --rsa-pkcs1-15 will cause the tool to use the older,
-deprecated pkcs#1 v1.5 signing algorithm when using RSA.  This can be
-enabled in the bootloader as wel, and may be needed if you are using
-an older version of the bootloader.