Update documentation re the urclock programmer

src/avrdude.1

@@ -158,7 +158,7 @@ to be backwards compatible with STK500 v1.x, and allows bootloaders to be
 much smaller, eg, as implemented in the urboot project
 https://github.com/stefanrueger/urboot. The programmer type ``urclock''
 caters for these urboot programmers. Owing to its backward compatibility,
-any bootloader that can be served by the arduino programmer can normally
+bootloaders that can be served by the arduino programmer can normally
 also be served by the urclock programmer.
 .Pp
 The BusPirate is a versatile tool that can also be used as an AVR programmer.
@@ -1174,7 +1174,9 @@ Urclock ID can be between 1 and 8 bytes.
 .It Ar showdate
 Show the last-modified date of the input file for the flash application,
 then exit. If the input file was stdin, the date will be that of the
-programming.
+programming.  Date and filename are part of the metadata that the urclock
+programmer stores by default in high flash just under the bootloader; see also
+-xnometadata.
 .It Ar showfilename
 Show the input filename (or title) of the last flash writing session, then exit.
 .It Ar title=<string>
@@ -1200,9 +1202,10 @@ just behind the vector table with the name VBL_ADDITIONAL_VECTOR.
 .It Ar showpart
 Show the part for which the bootloader was compiled, then exit.
 .It Ar bootsize=<size>
-Manual override for bootloader size. Urboot bootloaders put the number of used
+Manual override for bootloader size. Urboot bootloaders put the number of
-bootloader pages into a table at the top of flash, so the urclock programmer can
+used bootloader pages into a table at the top of the bootloader section,
-look up the bootloader size itself. In backward-compatibility mode, when programming
+ie, typically top of flash, so the urclock programmer can look up the
+bootloader size itself. In backward-compatibility mode, when programming
 via other bootloaders, this option can be used to tell the programmer the
 size, and therefore the location, of the bootloader.
 .It Ar vectornum=<arg>
@@ -1250,8 +1253,12 @@ frame is programmed.
 .It Ar delay=<n>
 Add a <n> ms delay after reset. This can be useful if a board takes a
 particularly long time to exit from external reset. <n> can be negative,
-in which case the default 80 ms delay after issuing reset will be
+in which case the default 110 ms delay after issuing reset will be
 shortened accordingly.
+.It Ar strict
+Urclock has a faster, but slightly different strategy than -c arduino to
+synchronise with the bootloader; some stk500v1 bootloaders cannot cope
+with this, and they need the -xstrict option.
 .It Ar help
 Show this help menu and exit
 .El

src/doc/avrdude.texi

@@ -280,14 +280,22 @@ the -D option will likely be required in this case, because the
 bootloader will rewrite the program memory, but no true chip erase can
 be performed.
 
-The Arduino (which is very similar to the STK500 1.x) is supported via
+Serial bootloaders that run a skeleton of the STK500 1.x protocol are supported via
-its own programmer type specification ``arduino''.  This programmer works for
+their own programmer type specification ``arduino''.  This programmer works for
 the Arduino Uno Rev3 or any AVR that runs the Optiboot bootloader.
 The number of connection retry attempts can be specified as an
 extended parameter. See the section on
 @emph{extended parameters}
 below for details.
 
+Urprotocol is a leaner version of the STK500 1.x protocol that is designed
+to be backwards compatible with STK500 v1.x; it allows bootloaders to be
+much smaller, eg, as implemented in the urboot project
+@uref{https://github.com/stefanrueger/urboot}. The programmer type ``urclock''
+caters for these urboot programmers. Owing to its backward compatibility,
+bootloaders that can be served by the arduino programmer can normally
+also be served by the urclock programmer.
+
 The BusPirate is a versatile tool that can also be used as an AVR programmer.
 A single BusPirate can be connected to up to 3 independent AVRs. See
 the section on
@@ -940,6 +948,117 @@ The Arduino programmer type accepts the following extended parameter:
 Overide the default number of connection retry attempt by using @var{VALUE}.
 @end table
 
+@cindex @code{-x} Urclock
+@item Urclock
+
+The urclock programmer type accepts the following extended parameters:
+@table @code
+@item @samp{showall}
+Show all info for the connected part, then exit. The @code{-xshow...} options
+below can be used to assemble a bespoke response consisting of a subset
+(or only one item) of all available relevant information about the
+connected part and bootloader.
+@item @samp{showid}
+Show a unique Urclock ID stored in either flash or EEPROM of the MCU, then exit.
+@item @samp{id=<E|F>.<addr>.<len>}
+Historically, the Urclock ID was a six-byte unique little-endian number
+stored in Urclock boards at EEPROM address 257. The location of this
+number can be set by the @code{-xid=<E|F>.<addr>.<len>} extended parameter. @code{E}
+stands for EEPROM and @code{F} stands for flash. A negative address addr counts
+from the end of EEPROM and flash, respectively. The length len of the
+Urclock ID can be between 1 and 8 bytes.
+@item @samp{showdate}
+Show the last-modified date of the input file for the flash application,
+then exit. If the input file was stdin, the date will be that of the
+programming. Date and filename are part of the metadata that the urclock
+programmer stores by default in high flash just under the bootloader; see also
+@code{-xnometadata}.
+@item @samp{showfilename}
+Show the input filename (or title) of the last flash writing session, then exit.
+@item @samp{title=<string>}
+When set, <string> will be used in lieu of the input filename. The maximum
+string length for the title/filename field is 254 bytes including
+terminating nul.
+@item @samp{showapp}
+Show the size of the programmed application, then exit.
+@item @samp{showstore}
+Show the size of the unused flash between the application and metadata, then exit.
+@item @samp{showmeta}
+Show the size of the metadata just below the bootloader, then exit.
+@item @samp{showboot}
+Show the size of the bootloader, then exit.
+@item @samp{showversion}
+Show bootloader version and capabilities, then exit.
+@item @samp{showvector}
+Show the vector number and name of the interrupt table vector used by the
+bootloader for starting the application, then exit. For hardware-supported
+bootloaders this will be vector 0 (Reset), and for vector bootloaders this
+will be any other vector number of the interrupt vector table or the slot
+just behind the vector table with the name @code{VBL_ADDITIONAL_VECTOR}.
+@item @samp{showpart}
+Show the part for which the bootloader was compiled, then exit.
+@item @samp{bootsize=<size>}
+Manual override for bootloader size. Urboot bootloaders put the number of
+used bootloader pages into a table at the top of the bootloader section,
+ie, typically top of flash, so the urclock programmer can look up the
+bootloader size itself. In backward-compatibility mode, when programming
+via other bootloaders, this option can be used to tell the programmer the
+size, and therefore the location, of the bootloader.
+@item @samp{vectornum=<arg>}
+Manual override for vector number. Urboot bootloaders put the vector
+number used by a vector bootloader into a table at the top of flash, so
+this option is normally not needed for urboot bootloaders. However, it is
+useful in backward-compatibility mode (or when the urboot bootloader does
+not offer flash read). Specifying a vector number in these circumstances
+implies a vector bootloader whilst the default assumption would be a
+hardware-supported bootloader.
+@item @samp{eepromrw}
+Manual override for asserting EEPROM read/write capability. Not normally
+needed for urboot bootloaders, but useful for in backward-compatibility
+mode if the bootloader offers EEPROM read/write.
+@item @samp{emulate_ce}
+If an urboot bootloader does not offer a chip erase command it will tell
+the urclock programmer so during handshake. In this case the urclock
+programmer emulates a chip erase, if warranted by user command line
+options, by filling the remainder of unused flash below the bootloader
+with 0xff. If this option is specified, the urclock programmer will assume
+that the bootloader cannot erase the chip itself. The option is useful
+for backwards-compatible bootloaders that do not implement chip erase.
+@item @samp{restore}
+Upload unchanged flash input files and trim below the bootloader if
+needed. This is most useful when one has a backup of the full flash and
+wants to play that back onto the device. No metadata are written in this
+case and no vector patching happens either if it is a vector bootloader.
+However, for vector bootloaders, even under the option @code{-xrestore} an
+input file will not be uploaded for which the reset vector does not point
+to the vector bootloader. This is to avoid writing an input file to the
+device that would render the vector bootloader not functional as it would
+not be reached after reset.
+@item @samp{initstore}
+On writing to flash fill the store space between the flash application and
+the metadata section with 0xff.
+@item @samp{nofilename}
+On writing to flash do not store the application input filename (nor a title).
+@item @samp{nodate}
+On writing to flash do not store the application input filename (nor a
+title) and no date either.
+@item @samp{nometadata}
+On writing to flash do not store any metadata. The full flash below the
+bootloader is available for the application. In particular, no data store
+frame is programmed.
+@item @samp{delay=<n>}
+Add a <n> ms delay after reset. This can be useful if a board takes a
+particularly long time to exit from external reset. <n> can be negative,
+in which case the default 110 ms delay after issuing reset will be
+shortened accordingly.
+@item @samp{strict}
+Urclock has a faster, but slightly different strategy than -c arduino to
+synchronise with the bootloader; some stk500v1 bootloaders cannot cope
+with this, and they need the @code{-xstrict} option.
+@item @samp{help}
+Show this help menu and exit
+@end table
+
 @cindex @code{-x} Buspirate
 @item BusPirate