Merge pull request #1908 from stefanrueger/documentation

Improve Documentation

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
@@ -809,161 +808,8 @@ of that by erasing pages before programming them unless -e (chip erase) or
 absence of the -e chip erase option any ATxmega or UPDI flash pages not
 affected by the programming will retain their previous content.
 .Pp
-Classic devices may have the following memories in addition to eeprom, flash, signature and lock:
-.Bl -tag -width "  calibration" -compact
-.It   calibration
-One or more bytes of RC oscillator calibration data
-.It   efuse
-Extended fuse byte
-.It   fuse
-Fuse byte in devices that have only a single fuse byte
-.It   hfuse
-High fuse byte
-.It   lfuse
-Low fuse byte
-.It   lock
-Lock byte
-.It prodsig
-Signature, calibration byte(s) and serial number in a small read-only memory,
-which is only documented to be available for ATmega324PB, ATmega328PB,
-ATtiny102 and ATtiny104;
-.Nm
-generally tries to make this memory available, also for parts where it is
-not documented, but not all programmers may be able to read this memory
-.It sigrow
-Memory alias for prodsig
-.It sernum
-The serial number part of prodsig; owing to scarce documentation this may not
-actually turn out to be a serial number or be readable by some programmers
-.It usersig
-Three extra flash pages for firmware settings; this memory is not erased
-during a chip erase. Only some classic parts,
-ATmega(64|128|256|644|1284|2564)RFR2, have a usersig memory. Usersig is
-different to flash in the sense that it can neither be accessed with ISP
-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
-memory region, e.g., using -T "erase usersig" -U
-usersig:w:parameters.hex:i
-.It io
-Volatile register memory; it cannot be accessed by external programming
-methods only by bootloaders, which has limited use unless the bootloader
-jumps to the application directly, i.e., without a WDT reset
-.It sram
-Volatile RAM memory; like io it cannot be accessed by external programming
-.El
-.Pp
-ATxmega devices have the following memories in addition to eeprom, flash, signature and lock:
-.Bl -tag -width "calibration" -compact
-.It application
-Application flash area
-.It apptable
-Application table flash area
-.It boot
-Boot flash area
-.It   calibration
-An area of 4 (ATxmega-A series) or 5 bytes (ATxmega-B/C/D/E) with
-oscillator calibration values; this is a sub-memory of prodsig
-.It fuses
-A logical memory of 7 bytes containing all fuseX of a part, which can be
-used to program all fuses at the same time; note that some fuse bytes will
-be reserved, though
-.It fuse0
-A.k.a. jtaguid: JTAG user ID for some devices
-.It fuse1
-Watchdog configuration
-.It fuse6
-Fault detection action configuration TC4/5 for ATxmega E series parts
-.It fuse Ns Em N
-Other fuse bytes of ATxmega devices, where
-.Em N
-is 2, 4 or 5, for system configuration
-.It prodsig
-The production signature row is a read-only memory section for factory
-programmed data such as the calibration values for oscillators or analogue
-modules; it also contains a serial number that consists of the production
-lot number, wafer number and wafer coordinates for the part
-.It sernum
-Serial number with a unique ID for the part consisting of 10 bytes; these
-are part of the prodsig memory above
-.It sigrow
-Memory alias for prodsig
-.It tempsense
-A two-byte memory, which is located within prodsig; it contains a 12-bit
-temperature sensor calibration value
-.It usersig
-Additional flash memory page that can be used for firmware settings; this
-memory is not erased during a chip erase
-.It io
-Volatile register memory;
-.Nm
-can read this memory but not write to it using external programming
-.It sram
-Volatile RAM memory; cannot be usefully accessed by external programming
-.El
-.Pp
-Modern 8-bit AVR devices have the following memories in addition to eeprom, flash, signature and lock:
-.Bl -tag -width "calibration" -compact
-.It fuse0
-A.k.a. wdtcfg: watchdog configuration
-.It fuse1
-A.k.a. bodcfg: brownout detection configuration
-.It fuse2
-A.k.a. osccfg: oscillator configuration
-.It fuse4
-A.k.a. tcd0cfg (not all devices): timer counter type D configuration
-.It fuse5
-A.k.a. syscfg0: system configuration 0
-.It fuse6
-A.k.a. syscfg1: system configuration 1
-.It fuse7
-A.k.a. append or codesize: either the end of the application code section or the code size in blocks of 256/512 bytes
-.It fuse8
-A.k.a. bootend or bootsize: end of the boot section or the boot size in blocks of 256/512 bytes
-.It fusea
-A.k.a. pdicfg: configures/locks updi access; it is the only fuse that consists of two bytes
-.It fuses
-A logical memory of up to 16 bytes containing all fuseX of a part, which can be
-used to program all fuses at the same time
-.It osc16err
-Two bytes typically describing the 16 MHz oscillator frequency error at 3 V and 5 V, respectively
-.It osc20err
-Two bytes typically describing the 20 MHz oscillator frequency error at 3 V and 5 V, respectively
-.It osccal16
-Two oscillator calibration bytes for 16 MHz
-.It osccal20
-Two oscillator calibration bytes for 20 MHz
-.It prodsig
-Read-only memory section for factory programmed data such as the
-signature, calibration values and serial number
-.It sigrow
-Memory alias for prodsig
-.It sernum
-Serial number with a unique ID for the part (10 or 16 bytes)
-.It tempsense
-Temperature sensor calibration values
-.It bootrow
-Extra page of memory that is only accessible by the MCU in bootloader
-code; UDPI can read and write this memory only when the device is
-unlocked
-.It userrow
-Extra page of EEPROM memory that can be used for firmware settings; this
-memory is not erased during a chip erase; UPDI cannot read this memory
-when the device is locked
-.It sib
-Special system information block memory with information about AVR family, chip revision etc.
-.It io
-Volatile register memory;
-.Nm
-can program this memory but this is of limited utility because anything
-written to the io memory will be undefined or lost after reset; writing to
-individual registers in the terminal can still be used, e.g., to test I/O
-ports
-.It sram
-Volatile RAM memory; can be read and written but contents will be lost after reset
-.El
+For a list of all known memories, please refer to the full documentation, eg,
+.Li https://github.com/avrdudes/avrdude/blob/main/avrdude.pdf
 .Pp
 The
 .Ar op
@@ -993,7 +839,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 +934,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 +1818,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 +1848,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

src/avrdude.conf.in

@@ -122,7 +122,7 @@ avrdude_conf_version = "@AVRDUDE_FULL_VERSION@";
 #       # STK500 parameters (parallel programming IO lines)
 #       pagel            = <num> ;                # page load pin name in hex, eg, 0xD7
 #       bs2              = <num> ;                # byte select 2 pin name in hex, eg, 0xA0
-#       serial           = <yes/no> ;             # can use serial downloading
+#       serial           = <yes/no> ;             # can use serial programming
 #       parallel         = <yes/no/pseudo> ;      # can use parallel programming
 #       # STK500v2 parameters, to be taken from Atmel's ATDF files
 #       timeout          = <num> ;
@@ -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,20 +3443,20 @@ programmer # jtag2updi
 # can be used for a -P <serialadapter>[:<serial number>] 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";
 #     usbsn                  = "0123456789";
 #     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

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 $<TARGET_FILE:avrdude> -C ${AVRDUDE_CONF} -p \? 2>&1 | grep = | wc -l >> version.texi
-    COMMAND echo -n "@set NUMPROGRAMMERS " >> version.texi
-    COMMAND $<TARGET_FILE:avrdude> -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 $<TARGET_FILE:avrdude> -C ${AVRDUDE_CONF} -p \? 2>&1 | grep = | wc -l >> avrstats.texi
+    COMMAND echo -n "@set NUMPROGRAMMERS " >> avrstats.texi
+    COMMAND $<TARGET_FILE:avrdude> -C ${AVRDUDE_CONF} -c \? 2>&1 | grep = | wc -l >> avrstats.texi
     VERBATIM
     )
 

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