From 97cc672fcb7de82d4ce40f1d258f01e6f723ced3 Mon Sep 17 00:00:00 2001 From: Stefan Rueger Date: Fri, 23 Aug 2024 20:57:29 +0100 Subject: [PATCH] Reduce use of upload/download terms --- src/avrdude.1 | 39 ++++++++++++++++---------------- src/avrdude.conf.in | 20 ++++++++--------- src/doc/CMakeLists.txt | 15 +++++++++---- src/doc/Makefile.am | 7 ++++++ src/doc/avrdude.texi | 51 +++++++++++++++++++++++------------------- src/stk500.c | 4 ++-- src/urclock.c | 20 ++++++++--------- 7 files changed, 87 insertions(+), 69 deletions(-) diff --git a/src/avrdude.1 b/src/avrdude.1 index 65b62e59..38dde393 100644 --- a/src/avrdude.1 +++ b/src/avrdude.1 @@ -54,7 +54,7 @@ .Op Fl V .Sh DESCRIPTION .Nm Avrdude -is a program for downloading code and data to Atmel AVR +is a program for downloading and uploading on-chip memories of Atmel AVR microcontrollers. .Nm Avrdude supports Atmel's STK500 programmer, @@ -186,15 +186,15 @@ AVR910, and the bootloader described in Atmel's application note AVR109 (which is also used by the AVR Butterfly evaluation board), are supported on a serial port. .Pp -Atmel's JTAG ICE (mkI, mkII, and 3) is supported as well to up- or download memory -areas from/to an AVR target (no support for on-chip debugging). -For the JTAG ICE mkII, JTAG, debugWIRE and ISP mode are supported, provided -it has a firmware revision of at least 4.14 (decimal). -JTAGICE3 also supports all of JTAG, debugWIRE, and ISP mode. -See below for the limitations of debugWIRE. -For ATxmega devices, the JTAG ICE mkII is supported in PDI mode, provided it -has a revision 1 hardware and firmware version of at least 5.37 (decimal). -For ATxmega devices, the JTAGICE3 is supported in PDI mode. +Atmel's JTAG ICE (mkI, mkII, and 3) is supported as well to uploading and +download memory areas of an AVR target (no support for on-chip debugging). +For the JTAG ICE mkII, JTAG, debugWIRE and ISP mode are supported, +provided it has a firmware revision of at least 4.14 (decimal). JTAGICE3 +also supports all of JTAG, debugWIRE, and ISP mode. See below for the +limitations of debugWIRE. For ATxmega devices, the JTAG ICE mkII is +supported in PDI mode, provided it has a revision 1 hardware and firmware +version of at least 5.37 (decimal). For ATxmega devices, the JTAGICE3 is +supported in PDI mode. .Pp Atmel-ICE (ARM/AVR) is supported in all modes (JTAG, PDI for Xmega, debugWIRE, ISP, UPDI). @@ -258,9 +258,8 @@ In a nutshell, this programmer consists of simple USB->UART adapter, diode and couple of resistors. It uses serial connection to provide UPDI interface. See the texinfo documentation for more details and known issues. .Pp -The jtag2updi programmer is supported, -and can program AVRs with a UPDI interface. -Jtag2updi is just a firmware that can be uploaded to an AVR, +The jtag2updi programmer is supported, and can program AVRs with a UPDI +interface. Jtag2updi is just a firmware that can be loaded onto an AVR, which enables it to interface with avrdude using the jtagice mkii protocol via a serial link. .Li https://github.com/ElTangas/jtag2updi @@ -285,7 +284,7 @@ for Teensy specific options. .Pp Input files can be provided, and output files can be written in different file formats, such as raw binary files containing the data -to download to the chip, Intel Hex format, or Motorola S-Record +to write to the chip, Intel Hex format, or Motorola S-Record format. There are a number of tools available to produce those files, like .Xr asl 1 @@ -844,7 +843,7 @@ serial programming nor written to by bootloaders; .Nm offers JTAG programming of classic-part usersig memories. As with all flash-type memories the -U option can only write 0-bits but not 1-bits. -Hence, usersig needs to be erased before a file can be uploaded to this +Hence, usersig needs to be erased before a file can be written to this memory region, e.g., using -T "erase usersig" -U usersig:w:parameters.hex:i .It io @@ -993,7 +992,7 @@ can be one of: .It Ar i Intel Hex .It Ar I -Intel Hex with comments on download and tolerance of checksum errors on upload +Intel Hex with comments on reading from, and tolerance of checksum errors, writing to the AVR .It Ar s Motorola S-Record .It Ar r @@ -1088,7 +1087,7 @@ More .Fl v options increase verbosity level. .It Fl V -Disable automatic verify check when uploading data with -U. +Disable automatic verify check when writing data to the AVR with -U. .It Fl x Ar extended_param Pass .Ar extended_param @@ -1972,12 +1971,12 @@ 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. .It Ar restore -Upload unchanged flash input files and trim below the bootloader if +Write 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 -x restore an -input file will not be uploaded for which the reset vector does not point +input file will not be written to the AVR 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. @@ -2002,7 +2001,7 @@ available space then a metadata code byte 0xff is stored nevertheless to indicate there are no further metadata available. In absence of -x nometadata, the default for the urclock programmer is to write as much metadata (filename, data and store information) as the size of the -uploaded application and the other extended options allow. The subtle +application and the other extended options allow. The subtle difference between -x nometadata and -x nostore is that the latter always explicitly stores in flash that no further metadata are available, so that a such prepared flash can always be queried with diff --git a/src/avrdude.conf.in b/src/avrdude.conf.in index 22791130..4dfbf8e4 100644 --- a/src/avrdude.conf.in +++ b/src/avrdude.conf.in @@ -122,7 +122,7 @@ avrdude_conf_version = "@AVRDUDE_FULL_VERSION@"; # # STK500 parameters (parallel programming IO lines) # pagel = ; # page load pin name in hex, eg, 0xD7 # bs2 = ; # byte select 2 pin name in hex, eg, 0xA0 -# serial = ; # can use serial downloading +# serial = ; # can use serial programming # parallel = ; # can use parallel programming # # STK500v2 parameters, to be taken from Atmel's ATDF files # timeout = ; @@ -961,7 +961,7 @@ programmer # arduino # - Reads/writes flash/EEPROM via the MCU bootloader and a serial connection # - Automatically resets an attached board via RTS/DTR into bootloader mode # - Implements urprotocol, a skeleton version of STK500v1 -# - Supports vector bootloaders by patching interrupt vectors during upload: +# - Supports vector bootloaders by patching interrupt vectors on flash writes # + Vector bootloaders run on all parts, no need for a HW boot section # + Can be much smaller than the smallest HW boot section of a part, eg, # 256 bytes for ATmega2560 (smallest HW boot section is 1024 bytes) @@ -970,7 +970,7 @@ programmer # arduino # - Provides a 4-byte metadata interface in top flash for # + Allowing applications to utilise unused flash similar to EEPROM # + Storing in top flash the file name and its last-modified date -# + Displaying file name and date of the last uploaded application +# + Displaying file name and date of the last programmed application # # See https://github.com/stefanrueger/urboot @@ -3443,7 +3443,7 @@ programmer # jtag2updi # can be used for a -P [:] port # specification instead of the created serial port. Per-user serialadapter # definitions in ~/.avrduderc or avrdude.rc files can add a serial number -# to assign a particular board a specific id and default upload baud rate: +# to assign a particular board a specific id and default baud rate: # # serialadapter parent "ft232r" # id = "bike-shed-door"; @@ -3451,12 +3451,12 @@ programmer # jtag2updi # baudrate = 250000; # ; # -# This is particularly useful for uploading to a bootloader as it allows -# specifying the port as -P bike-shed-door rather than having to figure -# out which serial port name the operating system has assigned to the -# plugged in bike-shed-door board at runtime. Note that each programmer -# that defines usbpid and sets is_serialadapter = yes can also be utilised -# as a serialadapter. +# This is particularly useful for programming via a bootloader as it allows +# specifying the port as -P bike-shed-door rather than having to figure out +# which serial port name the operating system has assigned to the plugged in +# bike-shed-door board at runtime. Note that each programmer that defines +# usbpid and sets is_serialadapter = yes can also be utilised as a +# serialadapter. #------------------------------------------------------------ # ch340 diff --git a/src/doc/CMakeLists.txt b/src/doc/CMakeLists.txt index 5a9a5de6..0f42c664 100644 --- a/src/doc/CMakeLists.txt +++ b/src/doc/CMakeLists.txt @@ -23,6 +23,7 @@ set(GENERATED_TEXINFOS programmers.texi programmer_types.texi parts.texi + avrstats.texi version.texi ) @@ -76,10 +77,16 @@ add_custom_command( COMMAND ${CMAKE_COMMAND} -E echo "@set EDITION ${DOCS_VERSION}" > version.texi COMMAND ${CMAKE_COMMAND} -E echo "@set VERSION ${DOCS_VERSION}" >> version.texi COMMAND ${CMAKE_COMMAND} -E echo "@set UPDATED ${DOCS_UPDATED}" >> version.texi - COMMAND echo -n "@set NUMPARTS " >> version.texi - COMMAND $ -C ${AVRDUDE_CONF} -p \? 2>&1 | grep = | wc -l >> version.texi - COMMAND echo -n "@set NUMPROGRAMMERS " >> version.texi - COMMAND $ -C ${AVRDUDE_CONF} -c \? 2>&1 | grep = | wc -l >> version.texi + VERBATIM + ) + +add_custom_command( + OUTPUT avrstats.texi + DEPENDS avrdude_binaries + COMMAND echo -n "@set NUMPARTS " >> avrstats.texi + COMMAND $ -C ${AVRDUDE_CONF} -p \? 2>&1 | grep = | wc -l >> avrstats.texi + COMMAND echo -n "@set NUMPROGRAMMERS " >> avrstats.texi + COMMAND $ -C ${AVRDUDE_CONF} -c \? 2>&1 | grep = | wc -l >> avrstats.texi VERBATIM ) diff --git a/src/doc/Makefile.am b/src/doc/Makefile.am index 144f6323..b17f37da 100644 --- a/src/doc/Makefile.am +++ b/src/doc/Makefile.am @@ -20,6 +20,7 @@ GENERATED_TEXINFOS = \ $(builddir)/programmers.texi \ $(builddir)/parts.texi \ $(builddir)/programmer_types.texi \ + $(builddir)/avrstats.texi \ $(builddir)/version.texi CLEANFILES = \ @@ -70,6 +71,12 @@ $(builddir)/parts.texi: ../avrdude$(EXEEXT) ../avrdude.conf $(srcdir)/parts.sed | grep = | sed -f $(srcdir)/parts.sed \ >parts.texi +$(builddir)/avrstats.texi: ../avrdude$(EXEEXT) ../avrdude.conf Makefile + echo -n "@set NUMPARTS " >> avrstats.texi + ../avrdude$(EXEEXT) -C ../avrdude.conf -p \? 2>&1 | grep = | wc -l >> avrstats.texi + echo -n "@set NUMPROGRAMMERS " >> avrstats.texi + ../avrdude$(EXEEXT) -C ../avrdude.conf -c \? 2>&1 | grep = | wc -l >> avrstats.texi + clean-local: rm -rf avrdude-html *.info diff --git a/src/doc/avrdude.texi b/src/doc/avrdude.texi index 18dace2c..59535ddc 100644 --- a/src/doc/avrdude.texi +++ b/src/doc/avrdude.texi @@ -14,6 +14,12 @@ @c @set EDITION 3.2.0 @c @set VERSION 3.2.0 +@include avrstats.texi + +@c +@c These contain various statistics used as @value{....} below +@c + @c This is a dir.info fragment to support semi-automated addition of @c manuals to an info tree. @dircategory AVR Programming & development tools. @@ -414,7 +420,7 @@ and couple of resistors. It uses serial connection to provide UPDI interface. The jtag2updi programmer is supported, and can program AVRs with a UPDI interface. -Jtag2updi is just a firmware that can be uploaded to an AVR, +Jtag2updi is just a firmware that can be loaded onto an AVR, which enables it to interface with avrdude using the jtagice mkii protocol via a serial link (@url{https://github.com/ElTangas/jtag2updi}). @@ -978,7 +984,7 @@ the file to read or write. Possible values are: Intel Hex @item I -Intel Hex with comments on download and tolerance of checksum errors on upload +Intel Hex with comments on reading from, and tolerance of checksum errors, writing to the AVR @cindex Motorola S-Record @item s @@ -1080,7 +1086,7 @@ More @code{-v} options increase verbosity level. @item -V @cindex Option @code{-V} @cindex @code{-V} -Disable automatic verify check when uploading data with @code{-U}. +Disable automatic verify check when writing data to the AVR with @code{-U}. @item -x @var{extended_param} @cindex Option @code{-x} @var{extended_param} @@ -1573,15 +1579,14 @@ that the bootloader cannot erase the chip itself. The option is useful for backwards-compatible bootloaders that do not implement chip erase. @cindex @code{flash} @item restore -Upload unchanged flash input files and trim below the bootloader if +Write unchanged flash input files to the AVR 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{-x restore} 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. +input file will not be written to the AVR for which the reset vector does not point +to the vector bootloader. This is to avoid loading an input file onto the +device that would render the vector bootloader becoming unreachable after reset. @cindex @code{flash} @item initstore On writing to flash fill the store space between the flash application and @@ -1607,7 +1612,7 @@ available space then a metadata code byte @code{0xff} is stored nevertheless to indicate there are no further metadata available. In absence of @code{-x nometadata}, the default for the urclock programmer is to write as much metadata (filename, data and store information) as the -size of the uploaded application and the other extended options allow. The +size of the application and the other extended options allow. The subtle difference between @code{-x nometadata} and @code{-x nostore} is that the latter always explicitly stores in flash that no further metadata are available, so that a such prepared flash can always be queried with @@ -1905,7 +1910,7 @@ shown for clarity that are not printed by AVRDUDE or the shell. @cindex @code{flash} @noindent -@strong{Download the file @code{diag.hex} to the ATmega128 chip} using the +@strong{Write the file @code{diag.hex} to the ATmega128 chip} using the STK500 programmer connected to the default serial port: @smallexample @@ -1978,9 +1983,9 @@ $ avrdude -cusbasp -patmega128 -qq -Ulfuse:r:-:h -Uhfuse:r:-:b -Uefuse:r:-:o @noindent @cindex @code{flash} @cindex @code{eeprom} -Using the default programmer, download the file @code{diag.hex} to -flash, @code{eeprom.hex} to EEPROM, and @strong{set the extended, high, and low -fuse bytes} to 0xff, 0x89, and 0x2e respectively: +Using the default programmer, write the file @code{diag.hex} to flash, the +file @code{eeprom.hex} to EEPROM, and @strong{set the extended, high, and +low fuse bytes} to 0xff, 0x89, and 0x2e respectively: @smallexample @cartouche @@ -3744,7 +3749,7 @@ that has only USB parameters defined. It can be used for a @code{-P [:]} port specification instead of the created serial port. Per-user serialadapter definitions in @code{~/.avrduderc} or @code{avrdude.rc} files can add a serial number to -assign a particular board a specific id and default upload baud rate: +assign a particular board a specific id and default communication baud rate: @smallexample serialadapter parent "ft232r" @@ -3755,12 +3760,12 @@ serialadapter parent "ft232r" @end smallexample @noindent -This is particularly useful for uploading to a bootloader as it allows -specifying the port as @code{-P bike-shed-door} rather than having to -figure out which serial port name the operating system has assigned to the -plugged in bike-shed-door board at runtime. Note that each programmer that -defines @code{usbpid} and sets @code{is_serialadapter = yes} can also be -utilised as a serialadapter. +This is particularly useful for programming through a bootloader as it +allows specifying the port as @code{-P bike-shed-door} rather than having +to figure out which serial port name the operating system has assigned to +the plugged in bike-shed-door board at runtime. Note that each programmer +that defines @code{usbpid} and sets @code{is_serialadapter = yes} can also +be utilised as a serialadapter. @c @c Node @@ -3795,7 +3800,7 @@ part # STK500 parameters (parallel programming IO lines) pagel = ; # page load pin name in hex, e.g., 0xD7 bs2 = ; # byte select 2 pin name in hex, e.g., 0xA0 - serial = ; # can use serial downloading + serial = ; # can use serial programming parallel = ; # can use parallel programming # STK500v2 parameters, to be taken from Atmel's ATDF files timeout = ; @@ -4323,7 +4328,7 @@ subroutines in the code for the respective @code{-c} programmer. The RDY LED is set once the programmer is initialised and switched off when AVRDUDE exits. During reading, writing or erasing the target the PGM LED flashes with around 2.5 Hz, whilst the VFY LED comes on during -U -verification of the uploaded contents. Errors are indicated with the ERR +verification of the written contents. Errors are indicated with the ERR LED. Assuming AVRDUDE got to the point where LEDs are accessible and the RDY @@ -5204,7 +5209,7 @@ different to flash in the sense that it can neither be accessed with ISP serial programming nor written to by bootloaders. AVRDUDE offers JTAG programming of classic-part usersig memories. As with all flash-type memories the @code{-U} option can only write 0-bits but not 1-bits. -Hence, usersig needs to be erased before a file can be uploaded to this +Hence, usersig needs to be erased before a file can be written to this memory region, e.g., using @code{-T "erase usersig" -U usersig:w:parameters.hex:i} @item io diff --git a/src/stk500.c b/src/stk500.c index 9fc0a674..cfac2820 100644 --- a/src/stk500.c +++ b/src/stk500.c @@ -908,8 +908,8 @@ retry: * Some bootloaders increment their copy of ext_addr_byte in that * situation, eg, when they use elpm rx, Z+ to read a byte from flash or * spm Z+ to write to flash whilst they keep ext_addr_byte in RAMPZ, - * which in turn gets incremented by Z+ at 64k page boundaries. So, if an - * upload with automated verify finishes just below 64k, AVRDUDE still + * which in turn gets incremented by Z+ at 64k page boundaries. So, if + * writing with automated verify finishes just below 64k, AVRDUDE still * holds ext_addr_byte at the current 64k segment whilst its copy in the * bootloader has been auto-incremented. Verifying the code from start * exposes the discrepancy. diff --git a/src/urclock.c b/src/urclock.c index 424d425d..62e193a4 100644 --- a/src/urclock.c +++ b/src/urclock.c @@ -23,7 +23,7 @@ * - Automatically resets an attached board via RTS/DTR into bootloader mode * - Works best in tandem with the urboot bootloader, but can deal with optiboot and similar * - Implements urprotocol, a communication protocol designed for small bootloader sizes - * - Supports vector bootloaders by patching relevant interrupt vectors during upload: + * - Supports vector bootloaders by patching relevant interrupt vectors on flash writes: * + Vector bootloaders run on all devices, not only those with a dedicated boot section * + Can be considerably smaller than the smallest dedicated boot section of a part, eg, * only 256 bytes for ATmega2560 with an otherwise smallest boot section of 1024 bytes @@ -31,8 +31,8 @@ * - Keeps the bootloader alive during interactive terminal sessions * - Provides a 4-byte metadata interface in top flash for * + Allowing applications to utilise unused flash in a similar fashion to EEPROM - * + Storing in top flash the file name and last-modified-date of the uploaded application - * + Displaying file name and date of the application that was last uploaded + * + Storing in top flash the file name and last-modified-date + * + Displaying file name and date of the last programmed application * * As an example, the urboot bootloader including EEPROM r/w for the popular ATmega328p is only 384 * bytes, which frees up 128 bytes. On an ATmega1284p the urboot bootloader without EEPROM r/w is @@ -278,8 +278,8 @@ typedef struct { int32_t storesize; // Store size // Metadata for free flash memory to be used for store support - char filename[254]; // Filename of uploaded application, must be max 254 bytes incl nul - int16_t yyyy; // Date stamp of uploaded application file: 4 digit year, + char filename[254]; // Filename of application, must be max 254 bytes incl nul + int16_t yyyy; // Date stamp of application file: 4 digit year, int8_t mm, dd, hr, mn; // Month (1..12), day (1..31), hour (0..23) and minute (0..59) uint8_t freeflash[3]; // 24-bit little endian number (storesize) uint8_t mcode; // 255 = no metadata, 0 = only freeflash, 1 = freeflash + date, @@ -297,7 +297,7 @@ typedef struct { // Extended parameters for Urclock int showall, // Show all pieces of info for connected part and exit showid, // ... Urclock ID - showdate, // ... last-modified date of last uploaded application + showdate, // ... last-modified date of last application file showfilename, // ... filename of last uploaded application showapp, // ... application size showstore, // ... store size @@ -555,7 +555,7 @@ static int urclock_flash_readhook(const PROGRAMMER *pgm, const AVRPART *p, const pmsg_notice2("%s %04d.%02d.%02d %02d.%02d meta %d boot %d\n", ur.filename, ur.yyyy, ur.mm, ur.dd, ur.hr, ur.mn, nmdata, ur.blend > ur.blstart? ur.blend-ur.blstart+1: 0); - // Force upload of exactly this file, no patching, no metadata update, just trim if too big + // Force writing of exactly this file, no patching, no metadata update, just trim if too big if(ur.restore) { if(size > maxsize) size = maxsize; @@ -633,7 +633,7 @@ static int urclock_flash_readhook(const PROGRAMMER *pgm, const AVRPART *p, const int reset32, appstart, appvecloc; appvecloc = ur.vblvectornum*vecsz; // Location of jump-to-application in vector table - reset16 = buf2uint16(flm->buf); // First reset word of to-be-uploaded application + reset16 = buf2uint16(flm->buf); // First reset word of to-be-written application reset32 = vecsz == 2? reset16: buf2uint32(flm->buf); /* @@ -750,7 +750,7 @@ nopatch_nometa: } } - // Emulate chip erase if bootloader unable to: mark all bytes for upload on first -U flash:w:... + // Emulate chip erase if bootloader unable to: mark all bytes for programming on first -U flash:w:... if(ur.emulate_ce) { for(int ai = 0; ai < maxsize; ai++) flm->tags[ai] = TAG_ALLOCATED; @@ -2441,7 +2441,7 @@ static int urclock_parseextparms(const PROGRAMMER *pgm, LISTID extparms) { {"showall", &ur.showall, NA, "Show all info for connected part and exit"}, {"showid", &ur.showid, NA, "Show Urclock ID and exit"}, {"showdate", &ur.showdate, NA, "Show last-modified date of flash application and exit"}, - {"showfilename", &ur.showfilename, NA,"Show filename of last uploaded application and exit"}, + {"showfilename", &ur.showfilename, NA,"Show filename of last written application and exit"}, {"showapp", &ur.showapp, NA, "Show application size and exit"}, {"showstore", &ur.showstore, NA, "Show store size and exit"}, {"showmeta", &ur.showmeta, NA, "Show metadata size and exit"},