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
-                           HEADER_SIZE [--pad PAD] [--rsa-pkcs1-15]
-                           infile outfile
+    Usage: imgtool.py sign [OPTIONS] INFILE OUTFILE
 
-    positional arguments:
-      infile
-      outfile
+      Create a signed or unsigned image
 
-    optional arguments:
-      -h, --help            show this help message and exit
-      -k filename, --key filename
-      --align ALIGN
-      -v VERSION, --version VERSION
-      -H HEADER_SIZE, --header-size HEADER_SIZE
-      --included-header     Image has gap for header
-      --pad PAD             Pad image to this many bytes, adding trailer magic
-      --rsa-pkcs1-15        Use old PKCS#1 v1.5 signature algorithm
+    Options:
+      -k, --key filename
+      --align [1|2|4|8]          [required]
+      -v, --version TEXT         [required]
+      -H, --header-size INTEGER  [required]
+      --pad-header               Add `--header-size` zeroed bytes at the beginning
+                                 of the image
+      -S, --slot-size INTEGER    Size of the slot where the image will be written
+                                 [required]
+      --pad                      Pad image to --slot-size bytes, adding trailer
+                                 magic
+      -M, --max-sectors INTEGER  When padding allow for this amount of sectors
+                                 (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
-prepended to the image.  If `--included-header` is given, the image
-must start with header-size bytes of zeros, and the header will be
-overwritten over these bytes.
+and will be a small power of two.  By default, the Zephyr build system will
+already prepended a zeroed header to the image.  If another build system is
+in use that does not automatically add this zeroed header, `--pad-header` can
+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.