Update documentation re the urclock programmer
This commit is contained in:
Stefan Rueger
parent
3a5f3735ba
commit
d774e87a59
|
|
@ -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
|
||||
bootloader pages into a table at the top of flash, so the urclock programmer can
|
||||
look up the bootloader size itself. In backward-compatibility mode, when programming
|
||||
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.
|
||||
.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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
its own programmer type specification ``arduino''. This programmer works for
|
||||
Serial bootloaders that run a skeleton of the STK500 1.x protocol are supported via
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue