1566 lines
58 KiB
Groff
1566 lines
58 KiB
Groff
.\"
|
|
.\" avrdude - A Downloader/Uploader for AVR device programmers
|
|
.\" Copyright (C) 2001, 2002, 2003, 2005 - 2020 Joerg Wunsch
|
|
.\"
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the GNU General Public License as published by
|
|
.\" the Free Software Foundation; either version 2 of the License, or
|
|
.\" (at your option) any later version.
|
|
.\"
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License
|
|
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
.\"
|
|
.\"
|
|
.\" $Id$
|
|
.\"
|
|
.Dd July 12, 2022
|
|
.Os
|
|
.Dt AVRDUDE 1
|
|
.Sh NAME
|
|
.Nm avrdude
|
|
.Nd driver program for ``simple'' Atmel AVR MCU programmer
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl p Ar partno
|
|
.Op Fl b Ar baudrate
|
|
.Op Fl B Ar bitclock
|
|
.Op Fl c Ar programmer-id
|
|
.Op Fl C Ar config-file
|
|
.Op Fl A
|
|
.Op Fl D
|
|
.Op Fl e
|
|
.Oo Fl E Ar exitspec Ns
|
|
.Op \&, Ns Ar exitspec
|
|
.Oc
|
|
.Op Fl F
|
|
.Op Fl i Ar delay
|
|
.Op Fl l Ar logfile
|
|
.Op Fl n
|
|
.Op Fl O
|
|
.Op Fl P Ar port
|
|
.Op Fl q
|
|
.Op Fl t
|
|
.Op Fl U Ar memtype:op:filename:filefmt
|
|
.Op Fl v
|
|
.Op Fl x Ar extended_param
|
|
.Op Fl V
|
|
.Sh DESCRIPTION
|
|
.Nm Avrdude
|
|
is a program for downloading code and data to Atmel AVR
|
|
microcontrollers.
|
|
.Nm Avrdude
|
|
supports Atmel's STK500 programmer,
|
|
Atmel's AVRISP and AVRISP mkII devices,
|
|
Atmel's STK600,
|
|
Atmel's JTAG ICE (mkI, mkII and 3, the latter two also in ISP mode),
|
|
programmers complying to AppNote AVR910 and AVR109 (including the Butterfly),
|
|
as well as a simple hard-wired
|
|
programmer connected directly to a
|
|
.Xr ppi 4
|
|
or
|
|
.Xr parport 4
|
|
parallel port, or to a standard serial port.
|
|
In the simplest case, the hardware consists just of a
|
|
cable connecting the respective AVR signal lines to the parallel port.
|
|
.Pp
|
|
The MCU is programmed in
|
|
.Em serial programming mode ,
|
|
so, for the
|
|
.Xr ppi 4
|
|
based programmer, the MCU signals
|
|
.Ql /RESET ,
|
|
.Ql SCK ,
|
|
.Ql SDI
|
|
and
|
|
.Ql SDO
|
|
of the AVR's SPI interface need to be connected to the
|
|
parallel port; older boards might use the labels MOSI for SDO or MISO for SDI.
|
|
Optionally, some otherwise
|
|
unused output pins of the parallel port can be used to supply power
|
|
for the MCU part, so it is also possible to construct a passive
|
|
stand-alone programming device. Some status LEDs indicating the
|
|
current operating state of the programmer can be connected, and a
|
|
signal is available to control a buffer/driver IC 74LS367 (or
|
|
74HCT367). The latter can be useful to decouple the parallel port
|
|
from the MCU when in-system programming is used.
|
|
.Pp
|
|
A number of equally simple bit-bang programming adapters that connect
|
|
to a serial port are supported as well, among them the popular
|
|
Ponyprog serial adapter, and the DASA and DASA3 adapters that used to
|
|
be supported by uisp(1).
|
|
Note that these adapters are meant to be attached to a physical serial
|
|
port.
|
|
Connecting to a serial port emulated on top of USB is likely to not
|
|
work at all, or to work abysmally slow.
|
|
.Pp
|
|
If you happen to have a Linux system with at least 4 hardware GPIOs
|
|
available (like almost all embedded Linux boards) you can do without
|
|
any additional hardware - just connect them to the SDO, SDI, RESET
|
|
and SCK pins on the AVR and use the linuxgpio programmer type. It bitbangs
|
|
the lines using the Linux sysfs GPIO interface. Of course, care should
|
|
be taken about voltage level compatibility. Also, although not strictly
|
|
required, it is strongly advisable to protect the GPIO pins from
|
|
overcurrent situations in some way. The simplest would be to just put
|
|
some resistors in series or better yet use a 3-state buffer driver like
|
|
the 74HC244. Have a look at http://kolev.info/blog/2013/01/06/avrdude-linuxgpio/ for a more
|
|
detailed tutorial about using this programmer type.
|
|
.Pp
|
|
Under a Linux installation with direct access to the SPI bus and GPIO
|
|
pins, such as would be found on a Raspberry Pi, the ``linuxspi''
|
|
programmer type can be used to directly connect to and program a chip
|
|
using the built in interfaces on the computer. The requirements to use
|
|
this type are that an SPI interface is exposed along with one GPIO
|
|
pin. The GPIO serves as the reset output since the Linux SPI drivers
|
|
do not hold chip select down when a transfer is not occurring and thus
|
|
it cannot be used as the reset pin. A readily available level
|
|
translator should be used between the SPI bus/reset GPIO and the chip
|
|
to avoid potentially damaging the computer's SPI controller in the
|
|
event that the chip is running at 5V and the SPI runs at 3.3V. The
|
|
GPIO chosen for reset can be configured in the avrdude configuration
|
|
file using the
|
|
.Li reset
|
|
entry under the linuxspi programmer, or
|
|
directly in the port specification. An external pull-up resistor
|
|
should be connected between the AVR's reset pin and Vcc. If Vcc is not
|
|
the same as the SPI voltage, this should be done on the AVR side of
|
|
the level translator to protect the hardware from damage.
|
|
.Pp
|
|
The
|
|
.Fl P Ar portname
|
|
option for this programmer defaults to
|
|
.Li /dev/spidev0.0:/dev/gpiochip0 .
|
|
.Pp
|
|
Atmel's STK500 programmer is also supported and connects to a serial
|
|
port.
|
|
Both, firmware versions 1.x and 2.x can be handled, but require a
|
|
different programmer type specification (by now).
|
|
Using firmware version 2, high-voltage programming is also supported,
|
|
both parallel and serial
|
|
(programmer types stk500pp and stk500hvsp).
|
|
.Pp
|
|
Wiring boards (e.g. Arduino Mega 2560 Rev3) are supported, utilizing STK500
|
|
V2.x protocol, but a simple DTR/RTS toggle is used to set the boards into
|
|
programming mode. The programmer type is ``wiring''. Note that 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.
|
|
.Pp
|
|
Serial bootloaders that run a skeleton of the STK500 1.x protocol are
|
|
supported via their own programmer type ``arduino''. This programmer works
|
|
for the Arduino Uno Rev3 or any AVR that runs the Optiboot bootloader.
|
|
.Pp
|
|
Urprotocol is a leaner version of the STK500 1.x protocol that is designed
|
|
to be backwards compatible with STK500 v1.x, and allows bootloaders to be
|
|
much smaller, e.g., 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,
|
|
bootloaders that can be served by the arduino programmer can normally
|
|
also be served by the urclock programmer. This may require specifying the
|
|
size of (to avrdude) unknown bootloaders in bytes using the
|
|
.Fl x Ar bootsize=<n>
|
|
option, which is necessary for the urclock programmer to enable it to
|
|
protect the bootloader from being overwritten. If an unknown bootloader
|
|
has EEPROM read/write capability then the option -x eepromrw informs
|
|
avrdude -c urclock of that capability.
|
|
.Pp
|
|
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
|
|
.Em extended parameters
|
|
below for details.
|
|
.Pp
|
|
Atmel's STK600 programmer is supported in ISP and high-voltage
|
|
programming modes, and connects through the USB.
|
|
For ATxmega devices, the STK600 is supported in PDI mode.
|
|
For ATtiny4/5/9/10 devices, the STK600 and AVRISP mkII are supported in TPI mode.
|
|
.Pp
|
|
The simple serial programmer described in Atmel's application note
|
|
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.
|
|
.Pp
|
|
Atmel-ICE (ARM/AVR) is supported in all modes (JTAG, PDI for Xmega, debugWIRE,
|
|
ISP, UPDI).
|
|
.Pp
|
|
Atmel's XplainedPro boards, using the EDBG protocol (CMSIS-DAP compatible),
|
|
are supported using the "jtag3" programmer type.
|
|
.Pp
|
|
Atmel's XplainedMini boards, using the mEDBG protocol,
|
|
are also supported using the "jtag3" programmer type.
|
|
.Pp
|
|
The AVR Dragon is supported in all modes (ISP, JTAG, HVSP, PP, debugWire).
|
|
When used in JTAG and debugWire mode, the AVR Dragon behaves similar to a
|
|
JTAG ICE mkII, so all device-specific comments for that device
|
|
will apply as well.
|
|
When used in ISP mode, the AVR Dragon behaves similar to an
|
|
AVRISP mkII (or JTAG ICE mkII in ISP mode), so all device-specific
|
|
comments will apply there.
|
|
In particular, the Dragon starts out with a rather fast ISP clock
|
|
frequency, so the
|
|
.Fl B Ar bitclock
|
|
option might be required to achieve a stable ISP communication.
|
|
For ATxmega devices, the AVR Dragon is supported in PDI mode, provided it
|
|
has a firmware version of at least 6.11 (decimal).
|
|
.Pp
|
|
The avrftdi, USBasp ISP and USBtinyISP adapters are also supported, provided
|
|
.Nm avrdude
|
|
has been compiled with libusb support.
|
|
USBasp ISP and USBtinyISP both feature simple firmware-only USB implementations,
|
|
running on an ATmega8 (or ATmega88), or ATtiny2313, respectively. If libftdi has
|
|
has been compiled in
|
|
.Nm avrdude ,
|
|
the avrftdi device adds support for many programmers using FTDI's 2232C/D/H
|
|
and 4232H parts running in MPSSE mode, which hard-codes (in the chip)
|
|
SCK to bit 1, SDO to bit 2, and SDI to bit 3. Reset is usually bit 4.
|
|
.Pp
|
|
The Atmel DFU bootloader is supported in both, FLIP protocol version 1
|
|
(AT90USB* and ATmega*U* devices), as well as version 2 (Xmega devices).
|
|
See below for some hints about FLIP version 1 protocol behaviour.
|
|
.Pp
|
|
The MPLAB(R) PICkit 4 and MPLAB(R) SNAP, are supported in JTAG, TPI, ISP,
|
|
PDI and UPDI mode.
|
|
The Curiosity Nano board is supported in UPDI mode. It is dubbed
|
|
.Dq PICkit on Board ,
|
|
thus the name
|
|
.Pa pkobn_updi .
|
|
.Pp
|
|
SerialUPDI programmer implementation is based on Microchip's
|
|
.Em pymcuprog Li https://github.com/microchip-pic-avr-tools/pymcuprog
|
|
utility, but it also contains some performance improvements included in
|
|
Spence Konde's
|
|
.Em DxCore
|
|
Arduino core
|
|
.Li https://github.com/SpenceKonde/DxCore .
|
|
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,
|
|
which enables it to interface with avrdude using the jtagice mkii protocol
|
|
via a serial link.
|
|
.Li https://github.com/ElTangas/jtag2updi
|
|
.Pp
|
|
The Micronucleus bootloader is supported for both protocol version V1
|
|
and V2. As the bootloader does not support reading from flash memory,
|
|
use the
|
|
.Fl V
|
|
option to prevent AVRDUDE from verifying the flash memory.
|
|
See the section on
|
|
.Em extended parameters
|
|
for Micronucleus specific options.
|
|
.Pp
|
|
The Teensy bootloader is supported for all AVR boards.
|
|
As the bootloader does not support reading from flash memory,
|
|
use the
|
|
.Fl V
|
|
option to prevent AVRDUDE from verifying the flash memory.
|
|
See the section on
|
|
.Em extended parameters
|
|
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
|
|
format. There are a number of tools available to produce those files,
|
|
like
|
|
.Xr asl 1
|
|
as a standalone assembler, or
|
|
.Xr avr-objcopy 1
|
|
for the final stage of the GNU toolchain for the AVR microcontroller.
|
|
.Pp
|
|
Provided
|
|
.Xr libelf 3
|
|
was present when compiling
|
|
.Nm avrdude ,
|
|
the input file can also be the final ELF file as produced by the linker.
|
|
The appropriate ELF section(s) will be examined, according to the memory
|
|
area to write to.
|
|
.Pp
|
|
.Nm Avrdude
|
|
can program the EEPROM and flash ROM memory cells of supported AVR
|
|
parts. Where supported by the serial instruction set, fuse bits and
|
|
lock bits can be programmed as well. These are implemented within
|
|
.Nm
|
|
as separate memory types and can be programmed using data from a file
|
|
(see the
|
|
.Fl U
|
|
option) or from terminal mode (see the
|
|
.Ar dump
|
|
and
|
|
.Ar write
|
|
commands). It is also possible to read the chip (provided it has not
|
|
been code-protected previously, of course) and store the data in a
|
|
file. Finally, a ``terminal'' mode is available that allows one to
|
|
interactively communicate with the MCU, and to display or program
|
|
individual memory cells.
|
|
On the STK500 and STK600 programmer, several operational parameters (target supply
|
|
voltage, target Aref voltage, programming clock) can be examined and changed
|
|
from within terminal mode as well.
|
|
.Ss Options
|
|
In order to control all the different operation modi, a number of options
|
|
need to be specified to
|
|
.Nm avrdude .
|
|
.Bl -tag -offset indent -width indent
|
|
.It Fl p Ar partno
|
|
This option specifies the MCU connected to the programmer. The MCU
|
|
descriptions are read from the config file. For currently supported MCUs use
|
|
? as partno, which will print a list of partno ids and official part names.
|
|
Both can be used with the -p option. If -p ? is specified with a specific
|
|
programmer, see -c below, then only those parts are output that the
|
|
programmer expects to be able to handle, together with the programming
|
|
interface(s) that can be used in that combination. In reality there can be
|
|
deviations from this list, particularly if programming is directly via a
|
|
bootloader.
|
|
.Pp
|
|
Following parts need special attention:
|
|
.Bl -tag -width "ATmega1234"
|
|
.It "AT90S1200"
|
|
The ISP programming protocol of the AT90S1200 differs in subtle ways
|
|
from that of other AVRs. Thus, not all programmers support this
|
|
device. Known to work are all direct bitbang programmers, and all
|
|
programmers talking the STK500v2 protocol.
|
|
.It "AT90S2343"
|
|
The AT90S2323 and ATtiny22 use the same algorithm.
|
|
.It "ATmega2560, ATmega2561"
|
|
Flash addressing above 128 KB is not supported by all
|
|
programming hardware. Known to work are jtag2, stk500v2,
|
|
and bit-bang programmers.
|
|
.It "ATtiny11"
|
|
The ATtiny11 can only be
|
|
programmed in high-voltage serial mode.
|
|
.El
|
|
.It Fl p Ar wildcard/flags
|
|
Run developer options for MCUs that are matched by wildcard. Whilst
|
|
their main use is for developers some flags can be of utility for users, e.g.,
|
|
avrdude -p m328p/S outputs AVRDUDE's understanding of ATmega328P MCU properties;
|
|
for more information run avrdude -p x/h.
|
|
.It Fl b Ar baudrate
|
|
Override the RS-232 connection baud rate specified in the respective
|
|
programmer's entry of the configuration file.
|
|
.It Fl B Ar bitclock
|
|
Specify the bit clock period for the JTAG, PDI, TPI, UPDI, or ISP
|
|
interface. The value is a floating-point number in microseconds.
|
|
Alternatively, the value might be suffixed with "Hz", "kHz" or
|
|
"MHz" in order to specify the bit clock frequency rather than a
|
|
period. Some programmers default their bit clock value to a 1
|
|
microsecond bit clock period, suitable for target MCUs running at 4
|
|
MHz clock and above. Slower MCUs need a correspondingly higher bit
|
|
clock period. Some programmers reset their bit clock value to the
|
|
default value when the programming software signs off, whilst others
|
|
store the last used bit clock value. It is recommended to always
|
|
specify the bit clock if read/write speed is important.
|
|
You can use the 'default_bitclock' keyword in your
|
|
.Pa ${HOME}/.config/avrdude/avrdude.rc
|
|
or
|
|
.Pa ${HOME}/.avrduderc
|
|
file to assign a default value to keep from having to specify this
|
|
option on every invocation.
|
|
.It Fl c Ar programmer-id
|
|
Use the programmer specified by the argument. Programmers and their pin
|
|
configurations are read from the config file (see the
|
|
.Fl C
|
|
option). New pin configurations can be easily added or modified
|
|
through the use of a config file to make
|
|
.Nm avrdude
|
|
work with different programmers as long as the programmer supports the
|
|
Atmel AVR serial program method. You can use the 'default_programmer'
|
|
keyword in your
|
|
.Pa ${HOME}/.config/avrdude/avrdude.rc
|
|
or
|
|
.Pa ${HOME}/.avrduderc
|
|
file to assign a default programmer to keep from having to specify
|
|
this option on every invocation.
|
|
A full list of all supported programmers is output to the terminal
|
|
by using ? as programmer-id.
|
|
If -c ? is specified with a specific part, see
|
|
-p above, then only those programmers are output that expect
|
|
to be able to handle this part, together with the programming interface(s) that can be
|
|
used in that combination. In reality there can be deviations from this list,
|
|
particularly if programming is directly via a bootloader.
|
|
.It Fl c Ar wildcard/flags
|
|
Run developer options for programmers that are matched by wildcard. Whilst
|
|
their main use is for developers some flags can be of utility for users, e.g.,
|
|
avrdude -c usbtiny/S shows AVRDUDE's understanding of usbtiny's properties;
|
|
for more information run avrdude -c x/h.
|
|
.It Fl C Ar config-file
|
|
Use the specified config file to load configuration data. This file
|
|
contains all programmer and part definitions that
|
|
.Nm avrdude
|
|
knows about.
|
|
See the config file, located at
|
|
.Pa ${PREFIX}/etc/avrdude.conf ,
|
|
which contains a description of the format.
|
|
.Pp
|
|
If
|
|
.Ar config-file
|
|
is written as
|
|
.Pa +filename
|
|
then this file is read after the system wide and user configuration
|
|
files. This can be used to add entries to the configuration
|
|
without patching your system wide configuration file. It can be used
|
|
several times, the files are read in same order as given on the command
|
|
line.
|
|
.It Fl A
|
|
Disable the automatic removal of trailing-0xFF sequences in file
|
|
input that is to be programmed to flash and in AVR reads from
|
|
flash memory. Normally, trailing 0xFFs can be discarded, as flash
|
|
programming requires the memory be erased to 0xFF beforehand.
|
|
.Fl A
|
|
should be used when the programmer hardware, or bootloader
|
|
software for that matter, does not carry out chip erase and
|
|
instead handles the memory erase on a page level. Popular
|
|
Arduino bootloaders exhibit this behaviour; for this reason
|
|
.Fl A
|
|
is engaged by default when specifying
|
|
. Fl c
|
|
arduino.
|
|
.It Fl D
|
|
Disable auto erase for flash. When the
|
|
.Fl U
|
|
option with flash memory is specified,
|
|
.Nm
|
|
will perform a chip erase before starting any of the programming
|
|
operations, since it generally is a mistake to program the flash
|
|
without performing an erase first. This option disables that.
|
|
Auto erase is not used for ATxmega devices as these devices can
|
|
use page erase before writing each page so no explicit chip erase
|
|
is required.
|
|
Note however that any page not affected by the current operation
|
|
will retain its previous contents.
|
|
Setting
|
|
.Fl D
|
|
implies
|
|
.Fl A.
|
|
.It Fl e
|
|
Causes a chip erase to be executed. This will reset the contents of the
|
|
flash ROM and EEPROM to the value
|
|
.Ql 0xff ,
|
|
and clear all lock bits.
|
|
Except for ATxmega devices which can use page erase,
|
|
it is basically a prerequisite command before the flash ROM can be
|
|
reprogrammed again. The only exception would be if the new
|
|
contents would exclusively cause bits to be programmed from the value
|
|
.Ql 1
|
|
to
|
|
.Ql 0 .
|
|
Note that in order to reprogram EEPROM cells, no explicit prior chip
|
|
erase is required since the MCU provides an auto-erase cycle in that
|
|
case before programming the cell.
|
|
.It Xo Fl E Ar exitspec Ns
|
|
.Op \&, Ns Ar exitspec
|
|
.Xc
|
|
By default,
|
|
.Nm
|
|
leaves the parallel port in the same state at exit as it has been
|
|
found at startup. This option modifies the state of the
|
|
.Ql /RESET
|
|
and
|
|
.Ql Vcc
|
|
lines the parallel port is left at, according to the
|
|
.Ar exitspec
|
|
arguments provided, as follows:
|
|
.Bl -tag -width noreset
|
|
.It Ar reset
|
|
The
|
|
.Ql /RESET
|
|
signal will be left activated at program exit, that is it will be held
|
|
.Em low ,
|
|
in order to keep the MCU in reset state afterwards. Note in particular
|
|
that the programming algorithm for the AT90S1200 device mandates that
|
|
the
|
|
.Ql /RESET
|
|
signal is active
|
|
.Em before
|
|
powering up the MCU, so in case an external power supply is used for this
|
|
MCU type, a previous invocation of
|
|
.Nm
|
|
with this option specified is one of the possible ways to guarantee this
|
|
condition.
|
|
.Em reset
|
|
is supported by the linuxspi and flip2 programmer options, as well as all
|
|
parallel port based programmers.
|
|
.It Ar noreset
|
|
The
|
|
.Ql /RESET
|
|
line will be deactivated at program exit, thus allowing the MCU target
|
|
program to run while the programming hardware remains connected.
|
|
.Em noreset
|
|
is supported by the linuxspi and flip2 programmer options, as well as all
|
|
parallel port based programmers.
|
|
.It Ar vcc
|
|
This option will leave those parallel port pins active
|
|
.Pq \&i. \&e. Em high
|
|
that can be used to supply
|
|
.Ql Vcc
|
|
power to the MCU.
|
|
.It Ar novcc
|
|
This option will pull the
|
|
.Ql Vcc
|
|
pins of the parallel port down at program exit.
|
|
.It Ar d_high
|
|
This option will leave the 8 data pins on the parallel port active.
|
|
.Pq \&i. \&e. Em high
|
|
.It Ar d_low
|
|
This option will leave the 8 data pins on the parallel port inactive.
|
|
.Pq \&i. \&e. Em low
|
|
.El
|
|
.Pp
|
|
Multiple
|
|
.Ar exitspec
|
|
arguments can be separated with commas.
|
|
.It Fl F
|
|
Normally,
|
|
.Nm
|
|
tries to verify that the device signature read from the part is
|
|
reasonable before continuing. Since it can happen from time to time
|
|
that a device has a broken (erased or overwritten) device signature
|
|
but is otherwise operating normally, this options is provided to
|
|
override the check.
|
|
Also, for programmers like the Atmel STK500 and STK600 which can
|
|
adjust parameters local to the programming tool (independent of an
|
|
actual connection to a target controller), this option can be used
|
|
together with
|
|
.Fl t
|
|
to continue in terminal mode.
|
|
Moreover, the option allows to continue despite failed initialization
|
|
of connection between a programmer and a target.
|
|
.It Fl i Ar delay
|
|
For bitbang-type programmers, delay for approximately
|
|
.Ar delay
|
|
microseconds between each bit state change.
|
|
If the host system is very fast, or the target runs off a slow clock
|
|
(like a 32 kHz crystal, or the 128 kHz internal RC oscillator), this
|
|
can become necessary to satisfy the requirement that the ISP clock
|
|
frequency must not be higher than 1/4 of the CPU clock frequency.
|
|
This is implemented as a spin-loop delay to allow even for very
|
|
short delays.
|
|
On Unix-style operating systems, the spin loop is initially calibrated
|
|
against a system timer, so the number of microseconds might be rather
|
|
realistic, assuming a constant system load while
|
|
.Nm
|
|
is running.
|
|
On Win32 operating systems, a preconfigured number of cycles per
|
|
microsecond is assumed that might be off a bit for very fast or very
|
|
slow machines.
|
|
.It Fl l Ar logfile
|
|
Use
|
|
.Ar logfile
|
|
rather than
|
|
.Va stderr
|
|
for diagnostics output.
|
|
Note that initial diagnostic messages (during option parsing) are still
|
|
written to
|
|
.Va stderr
|
|
anyway.
|
|
.It Fl n
|
|
No-write - disables actually writing data to the MCU (useful for debugging
|
|
.Nm avrdude
|
|
).
|
|
.It Fl O
|
|
Perform a RC oscillator run-time calibration according to Atmel
|
|
application note AVR053.
|
|
This is only supported on the STK500v2, AVRISP mkII, and JTAG ICE mkII
|
|
hardware.
|
|
Note that the result will be stored in the EEPROM cell at address 0.
|
|
.It Fl P Ar port
|
|
Use
|
|
.Ar port
|
|
to identify the device to which the programmer is attached. By
|
|
default the
|
|
.Pa /dev/ppi0
|
|
port is used, but if the programmer type normally connects to the
|
|
serial port, the
|
|
.Pa /dev/cuaa0
|
|
port is the default. If you need to use a different parallel or
|
|
serial port, use this option to specify the alternate port name.
|
|
.Pp
|
|
On Win32 operating systems, the parallel ports are referred to as lpt1
|
|
through lpt3, referring to the addresses 0x378, 0x278, and 0x3BC,
|
|
respectively. If the parallel port can be accessed through a different
|
|
address, this address can be specified directly, using the common C
|
|
language notation (i. e., hexadecimal values are prefixed by
|
|
.Ql 0x
|
|
).
|
|
.Pp
|
|
For the JTAG ICE mkII and JTAGICE3, if
|
|
.Nm
|
|
has been configured with libusb support,
|
|
.Ar port
|
|
can alternatively be specified as
|
|
.Pa usb Ns Op \&: Ns Ar serialno .
|
|
This will cause
|
|
.Nm
|
|
to search the programmer on USB.
|
|
If
|
|
.Ar serialno
|
|
is also specified, it will be matched against the serial number read
|
|
from any JTAG ICE mkII found on USB.
|
|
The match is done after stripping any existing colons from the given
|
|
serial number, and right-to-left, so only the least significant bytes
|
|
from the serial number need to be given.
|
|
.Pp
|
|
As the AVRISP mkII device can only be talked to over USB, the very
|
|
same method of specifying the port is required there.
|
|
.Pp
|
|
For the USB programmer "AVR-Doper" running in HID mode, the port must
|
|
be specified as
|
|
.Ar avrdoper.
|
|
Libhidapi support is required on Unix and Mac OS but not on Windows. For more
|
|
information about AVR-Doper see http://www.obdev.at/avrusb/avrdoper.html.
|
|
.Pp
|
|
For the USBtinyISP, which is a simplistic device not implementing
|
|
serial numbers, multiple devices can be distinguished by their
|
|
location in the USB hierarchy. See the respective
|
|
.Em Troubleshooting
|
|
entry in the detailed documentation for examples.
|
|
.Pp
|
|
For the XBee programmer the target MCU is to be programmed wirelessly over a
|
|
ZigBee mesh using the XBeeBoot bootloader. The ZigBee 64-bit address for the
|
|
target MCU's own XBee device must be supplied as a 16-character hexadecimal
|
|
value as a
|
|
.Ar port
|
|
prefix, followed by the
|
|
.Ql @
|
|
character, and the serial device to connect to a second directly contactable
|
|
XBee device associated with the same mesh (with a default baud rate of 9600).
|
|
This may look similar to:
|
|
.Pa 0013a20000000001@/dev/tty.serial .
|
|
.Pp
|
|
For diagnostic purposes, if the target MCU with an XBeeBoot bootloader is
|
|
connected directly to the serial port, the 64-bit address field can be
|
|
omitted. In this mode the default baud rate will be 19200.
|
|
.Pp
|
|
For programmers that attach to a serial port using some kind of
|
|
higher level protocol (as opposed to bit-bang style programmers),
|
|
.Ar port
|
|
can be specified as
|
|
.Pa net Ns \&: Ns Ar host Ns \&: Ns Ar port .
|
|
In this case, instead of trying to open a local device, a TCP
|
|
network connection to (TCP)
|
|
.Ar port
|
|
on
|
|
.Ar host
|
|
is established.
|
|
Square brackets may be placed around
|
|
.Ar host
|
|
to improve readability, for numeric IPv6 addresses (e.g.
|
|
.Li net:[2001:db8::42]:1337 ) .
|
|
The remote endpoint is assumed to be a terminal or console server
|
|
that connects the network stream to a local serial port where the
|
|
actual programmer has been attached to.
|
|
The port is assumed to be properly configured, for example using a
|
|
transparent 8-bit data connection without parity at 115200 Baud
|
|
for a STK500.
|
|
.Pp
|
|
Note: The ability to handle IPv6 hostnames and addresses is limited to
|
|
Posix systems (by now).
|
|
.It Fl q
|
|
Disable (or quell) output of the progress bar while reading or writing
|
|
to the device. Specify it more often for even quieter operations.
|
|
.It Fl s, u
|
|
These options used to control the obsolete "safemode" feature which
|
|
is no longer present. They are silently ignored for backwards compatibility.
|
|
.It Fl t
|
|
Tells
|
|
.Nm
|
|
to enter the interactive ``terminal'' mode instead of up- or downloading
|
|
files. See below for a detailed description of the terminal mode.
|
|
.It Xo Fl U Ar memtype Ns
|
|
.Ar \&: Ns Ar op Ns
|
|
.Ar \&: Ns Ar filename Ns
|
|
.Op \&: Ns Ar format
|
|
.Xc
|
|
Perform a memory operation as indicated. The
|
|
.Ar memtype
|
|
field specifies the memory type to operate on.
|
|
The available memory types are device-dependent, the actual
|
|
configuration can be viewed with the
|
|
.Cm part
|
|
command in terminal mode.
|
|
Typically, a device's memory configuration at least contains
|
|
the memory types
|
|
.Ar flash
|
|
and
|
|
.Ar eeprom .
|
|
All memory types currently known are:
|
|
.Bl -tag -width "calibration" -compact
|
|
.It calibration
|
|
One or more bytes of RC oscillator calibration data.
|
|
.It eeprom
|
|
The EEPROM of the device.
|
|
.It efuse
|
|
The extended fuse byte.
|
|
.It flash
|
|
The flash ROM of the device.
|
|
.It fuse
|
|
The fuse byte in devices that have only a single fuse byte.
|
|
.It hfuse
|
|
The high fuse byte.
|
|
.It lfuse
|
|
The low fuse byte.
|
|
.It lock
|
|
The lock byte.
|
|
.It signature
|
|
The three device signature bytes (device ID).
|
|
.It fuse Ns Em N
|
|
The fuse bytes of ATxmega devices,
|
|
.Em N
|
|
is an integer number
|
|
for each fuse supported by the device.
|
|
.It application
|
|
The application flash area of ATxmega devices.
|
|
.It apptable
|
|
The application table flash area of ATxmega devices.
|
|
.It boot
|
|
The boot flash area of ATxmega devices.
|
|
.It prodsig
|
|
The production signature (calibration) area of ATxmega devices.
|
|
.It usersig
|
|
The user signature area of ATxmega devices.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar op
|
|
field specifies what operation to perform:
|
|
.Bl -tag -width noreset
|
|
.It Ar r
|
|
read device memory and write to the specified file
|
|
.It Ar w
|
|
read data from the specified file and write to the device memory
|
|
.It Ar v
|
|
read data from both the device and the specified file and perform a verify
|
|
.El
|
|
.Pp
|
|
The
|
|
.Ar filename
|
|
field indicates the name of the file to read or write.
|
|
The
|
|
.Ar format
|
|
field is optional and contains the format of the file to read or
|
|
write.
|
|
.Ar Format
|
|
can be one of:
|
|
.Bl -tag -width sss
|
|
.It Ar i
|
|
Intel Hex
|
|
.It Ar I
|
|
Intel Hex with comments on download and tolerance of checksum errors on upload
|
|
.It Ar s
|
|
Motorola S-record
|
|
.It Ar r
|
|
raw binary; little-endian byte order, in the case of the flash ROM data
|
|
.It Ar e
|
|
ELF (Executable and Linkable Format)
|
|
.It Ar m
|
|
immediate; actual byte values specified on the command line, separated
|
|
by commas or spaces. This is good for programming fuse bytes without
|
|
having to create a single-byte file or enter terminal mode.
|
|
.It Ar a
|
|
auto detect; valid for input only, and only if the input is not
|
|
provided at
|
|
.Em stdin .
|
|
.It Ar d
|
|
decimal; this and the following formats are only valid on output.
|
|
They generate one line of output for the respective memory section,
|
|
forming a comma-separated list of the values.
|
|
This can be particularly useful for subsequent processing, like for
|
|
fuse bit settings.
|
|
.It Ar h
|
|
hexadecimal; each value will get the string
|
|
.Em 0x
|
|
prepended.
|
|
Only valid on output.
|
|
.It Ar o
|
|
octal; each value will get a
|
|
.Em 0
|
|
prepended unless it is less than 8 in which case it gets no prefix.
|
|
Only valid on output.
|
|
.It Ar b
|
|
binary; each value will get the string
|
|
.Em 0b
|
|
prepended.
|
|
Only valid on output.
|
|
.El
|
|
.Pp
|
|
The default is to use auto detection for input files, and raw binary
|
|
format for output files.
|
|
Note that if
|
|
.Ar filename
|
|
contains a colon, the
|
|
.Ar format
|
|
field is no longer optional since the filename part following the colon
|
|
would otherwise be misinterpreted as
|
|
.Ar format .
|
|
.Pp
|
|
When reading any kind of flash memory area (including the various sub-areas
|
|
in Xmega devices), the resulting output file will be truncated to not contain
|
|
trailing 0xFF bytes which indicate unprogrammed (erased) memory.
|
|
Thus, if the entire memory is unprogrammed, this will result in an output
|
|
file that has no contents at all.
|
|
.Pp
|
|
As an abbreviation, the form
|
|
.Fl U Ar filename
|
|
is equivalent to specifying
|
|
.Fl U Em flash:w: Ns Ar filename Ns :a .
|
|
This will only work if
|
|
.Ar filename
|
|
does not have a colon in it.
|
|
.It Fl v
|
|
Enable verbose output.
|
|
More
|
|
.Fl v
|
|
options increase verbosity level.
|
|
.It Fl V
|
|
Disable automatic verify check when uploading data.
|
|
.It Fl x Ar extended_param
|
|
Pass
|
|
.Ar extended_param
|
|
to the chosen programmer implementation as an extended parameter.
|
|
The interpretation of the extended parameter depends on the
|
|
programmer itself.
|
|
See below for a list of programmers accepting extended parameters.
|
|
.El
|
|
.Ss Terminal mode
|
|
In this mode,
|
|
.Nm
|
|
only initializes communication with the MCU, and then awaits user
|
|
commands on standard input. Commands and parameters may be
|
|
abbreviated to the shortest unambiguous form. Terminal mode provides
|
|
a command history using
|
|
.Xr readline 3 ,
|
|
so previously entered command lines can be recalled and edited. The
|
|
following commands are currently implemented for all programmers:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar dump memory addr len
|
|
Read
|
|
.Ar len
|
|
bytes from the specified memory area, and display them in the usual
|
|
hexadecimal and ASCII form.
|
|
.It Ar dump memory addr ...
|
|
Read all bytes from the specified memory starting at address
|
|
.Ar addr,
|
|
and display them.
|
|
.It Ar dump memory addr
|
|
Read 256 bytes from the specified memory area, and display them.
|
|
.It Ar dump memory ...
|
|
Read all bytes from the specified memory, and display them.
|
|
.It Ar dump memory
|
|
Continue dumping the memory contents for another
|
|
.Ar 256
|
|
bytes where the previous
|
|
.Ar dump
|
|
command left off.
|
|
.It Ar read
|
|
can be used as an alias for dump
|
|
.It Ar write memory addr data[,] {data[,]}
|
|
Manually program the respective memory cells, starting at address
|
|
.Ar addr ,
|
|
using the data items provided.
|
|
The terminal implements reading from and writing to flash and EEPROM type
|
|
memories normally through a cache and paged access functions. All other
|
|
memories are directly written to without use of a cache. Some
|
|
older parts without paged access will also have flash and EEPROM directly
|
|
accessed without cache.
|
|
.Pp
|
|
.Ar data
|
|
can be hexadecimal, octal or decimal integers, floating point numbers
|
|
or C-style strings and characters. For integers, an optional case-insensitive
|
|
suffix specifies the data size: HH 8 bit, H/S 16 bit, L 32 bit, LL 64 bit.
|
|
Suffix D indicates a 64-bit double, F a 32-bit float, whilst a floating point
|
|
number without suffix defaults to 32-bit float. Hexadecimal floating point
|
|
notation is supported. An ambiguous trailing suffix, e.g., 0x1.8D, is read as
|
|
no-suffix float where D is part of the mantissa; use a zero exponent 0x1.8p0D
|
|
to clarify.
|
|
.Pp
|
|
An optional U suffix makes integers unsigned. Ordinary 0x hex integers are
|
|
always treated as unsigned. +0x or -0x hex numbers are treated as signed
|
|
unless they have a U suffix. Unsigned integers cannot be larger than 2^64-1.
|
|
If n is an unsigned integer then -n is also a valid unsigned integer as in C.
|
|
Signed integers must fall into the [-2^63, 2^63-1] range or a correspondingly
|
|
smaller range when a suffix specifies a smaller type.
|
|
.Pp
|
|
Ordinary 0x hex integers with n hex digits (counting leading zeros) use the
|
|
smallest size of one, two, four and eight bytes that can accommodate any
|
|
n-digit hex integer. If an integer suffix specifies a size explicitly the
|
|
corresponding number of least significant bytes are written, and a warning
|
|
shown if the number does not fit into the desired representation. Otherwise,
|
|
unsigned integers occupy the smallest of one, two, four or eight bytes
|
|
needed. Signed numbers are allowed to fit into the smallest signed or
|
|
smallest unsigned representation: For example, 255 is stored as one byte as
|
|
255U would fit in one byte, though as a signed number it would not fit into a
|
|
one-byte interval [-128, 127]. The number -1 is stored in one byte whilst -1U
|
|
needs eight bytes as it is the same as 0xFFFFffffFFFFffffU.
|
|
.Pp
|
|
One trailing comma at the end of
|
|
.Ar data
|
|
items is ignored to facilitate copy & paste of lists.
|
|
.It Ar write memory addr len data[,] {data[,]} ...
|
|
The ellipsis ... form writes <len> bytes padded by repeating the last
|
|
.Ar data
|
|
item.
|
|
.It Ar flush
|
|
Synchronise with the device all pending cached writes to EEPROM or flash.
|
|
With some programmer and part combinations, flash (and sometimes EEPROM,
|
|
too) looks like a NOR memory, ie, one can only write 0 bits, not 1 bits.
|
|
When this is detected, either page erase is deployed (e.g., with parts that
|
|
have PDI/UPDI interfaces), or if that is not available, both EEPROM and
|
|
flash caches are fully read in, a chip erase command is issued and both
|
|
EEPROM and flash are written back to the device. Hence, it can take
|
|
minutes to ensure that a single previously cleared bit is set and,
|
|
therefore, this command should be used sparingly.
|
|
.It Ar abort
|
|
Normally, caches are only ever
|
|
actually written to the device when using the
|
|
.Ar flush
|
|
command, at the end of the terminal session after typing
|
|
.Ar quit ,
|
|
or after EOF on input is encountered. The abort command resets
|
|
the cache discarding all previous writes to the flash and EEPROM cache.
|
|
.It Ar erase
|
|
Perform a chip erase and discard all pending writes to EEPROM and flash.
|
|
.It Ar sig
|
|
Display the device signature bytes.
|
|
.It Ar part
|
|
Display the current part settings and parameters. Includes chip
|
|
specific information including all memory types supported by the
|
|
device, read/write timing, etc.
|
|
.It Ar verbose Op Ar level
|
|
Change (when
|
|
.Ar level
|
|
is provided), or display the verbosity level.
|
|
The initial verbosity level is controlled by the number of
|
|
.Fl v
|
|
options given on the commandline.
|
|
.It Ar quell Op Ar level
|
|
Change (when
|
|
.Ar level
|
|
is provided), or display the quell level. 1 is used to suppress progress reports.
|
|
2 or higher yields in progressively quieter operations.
|
|
The initial quell level is controlled by the number of
|
|
.Fl q
|
|
options given on the commandline.
|
|
.It Ar \&?
|
|
.It Ar help
|
|
Give a short on-line summary of the available commands.
|
|
.It Ar quit
|
|
Leave terminal mode and thus
|
|
.Nm avrdude .
|
|
.El
|
|
.Pp
|
|
The terminal commands below may only be implemented on some specific programmers, and may therefore not be available in the help menu.
|
|
.Bl -tag -offset indent -width indent
|
|
.It pgerase memory addr
|
|
Erase one page of the memory specified.
|
|
.It Ar send b1 b2 b3 b4
|
|
Send raw instruction codes to the AVR device. If you need access to a
|
|
feature of an AVR part that is not directly supported by
|
|
.Nm ,
|
|
this command allows you to use it, even though
|
|
.Nm
|
|
does not implement the command. When using direct SPI mode, up to 3 bytes
|
|
can be omitted.
|
|
.It Ar spi
|
|
Enter direct SPI mode. The
|
|
.Em pgmled
|
|
pin acts as chip select.
|
|
.Em Supported on parallel bitbang programmers, and partially by USBtiny.
|
|
.It Ar pgm
|
|
Return to programming mode (from direct SPI mode).
|
|
.It Ar vtarg voltage
|
|
Set the target's supply voltage to
|
|
.Ar voltage
|
|
Volts.
|
|
.Em Supported on the STK500 and STK600 programmer.
|
|
.It Ar varef Oo Ar channel Oc Ar voltage
|
|
Set the adjustable voltage source to
|
|
.Ar voltage
|
|
Volts.
|
|
This voltage is normally used to drive the target's
|
|
.Em Aref
|
|
input on the STK500.
|
|
On the Atmel STK600, two reference voltages are available, which
|
|
can be selected by the optional
|
|
.Ar channel
|
|
argument (either 0 or 1).
|
|
.Em Supported on the STK500 and STK600 programmer.
|
|
.It Ar fosc freq Ns Op M Ns \&| Ns k
|
|
Set the programming oscillator to
|
|
.Ar freq
|
|
Hz.
|
|
An optional trailing letter
|
|
.Ar \&M
|
|
multiplies by 1E6, a trailing letter
|
|
.Ar \&k
|
|
by 1E3.
|
|
.Em Supported on the STK500 and STK600 programmer.
|
|
.It Ar fosc off
|
|
Turn the programming oscillator off.
|
|
.Em Supported on the STK500 and STK600 programmer.
|
|
.It Ar sck period
|
|
.Em STK500 and STK600 programmer:
|
|
Set the SCK clock period to
|
|
.Ar period
|
|
microseconds.
|
|
.Em JTAG ICE:
|
|
Set the JTAG ICE bit clock period to
|
|
.Ar period
|
|
microseconds.
|
|
Note that unlike STK500 settings, this setting will be reverted to
|
|
its default value (approximately 1 microsecond) when the programming
|
|
software signs off from the JTAG ICE.
|
|
This parameter can also be used on the JTAG ICE mkII, JTAGICE3, and Atmel-ICE to specify the
|
|
ISP clock period when operating the ICE in ISP mode.
|
|
.It Ar parms
|
|
.Em STK500 and STK600 programmer:
|
|
Display the current voltage and programming oscillator parameters.
|
|
.Em JTAG ICE:
|
|
Display the current target supply voltage and JTAG bit clock rate/period.
|
|
.Em Other programmers:
|
|
Display the programmer specific parameters.
|
|
.El
|
|
.Ss Default Parallel port pin connections
|
|
(these can be changed, see the
|
|
.Fl c
|
|
option)
|
|
.TS
|
|
ll.
|
|
\fBPin number\fP \fBFunction\fP
|
|
2-5 Vcc (optional power supply to MCU)
|
|
7 /RESET (to MCU)
|
|
8 SCK (to MCU)
|
|
9 SDO (to MCU)
|
|
10 SDI (from MCU)
|
|
18-25 GND
|
|
.TE
|
|
.Ss debugWire limitations
|
|
The debugWire protocol is Atmel's proprietary one-wire (plus ground)
|
|
protocol to allow an in-circuit emulation of the smaller AVR devices,
|
|
using the
|
|
.Ql /RESET
|
|
line.
|
|
DebugWire mode is initiated by activating the
|
|
.Ql DWEN
|
|
fuse, and then power-cycling the target.
|
|
While this mode is mainly intended for debugging/emulation, it
|
|
also offers limited programming capabilities.
|
|
Effectively, the only memory areas that can be read or programmed
|
|
in this mode are flash ROM and EEPROM.
|
|
It is also possible to read out the signature.
|
|
All other memory areas cannot be accessed.
|
|
There is no
|
|
.Em chip erase
|
|
functionality in debugWire mode; instead, while reprogramming the
|
|
flash ROM, each flash ROM page is erased right before updating it.
|
|
This is done transparently by the JTAG ICE mkII (or AVR Dragon).
|
|
The only way back from debugWire mode is to initiate a special
|
|
sequence of commands to the JTAG ICE mkII (or AVR Dragon), so the
|
|
debugWire mode will be temporarily disabled, and the target can
|
|
be accessed using normal ISP programming.
|
|
This sequence is automatically initiated by using the JTAG ICE mkII
|
|
or AVR Dragon in ISP mode, when they detect that ISP mode cannot be
|
|
entered.
|
|
.Ss FLIP version 1 idiosyncrasies
|
|
Bootloaders using the FLIP protocol version 1 experience some very
|
|
specific behaviour.
|
|
.Pp
|
|
These bootloaders have no option to access memory areas other than
|
|
Flash and EEPROM.
|
|
.Pp
|
|
When the bootloader is started, it enters a
|
|
.Em security mode
|
|
where the only acceptable access is to query the device configuration
|
|
parameters (which are used for the signature on AVR devices).
|
|
The only way to leave this mode is a
|
|
.Em chip erase .
|
|
As a chip erase is normally implied by the
|
|
.Fl U
|
|
option when reprogramming the flash, this peculiarity might not be
|
|
very obvious immediately.
|
|
.Pp
|
|
Sometimes, a bootloader with security mode already disabled seems to
|
|
no longer respond with sensible configuration data, but only 0xFF for
|
|
all queries.
|
|
As these queries are used to obtain the equivalent of a signature,
|
|
.Nm
|
|
can only continue in that situation by forcing the signature check
|
|
to be overridden with the
|
|
.Fl F
|
|
option.
|
|
.Pp
|
|
A
|
|
.Em chip erase
|
|
might leave the EEPROM unerased, at least on some
|
|
versions of the bootloader.
|
|
.Ss Programmers accepting extended parameters
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar JTAG ICE mkII
|
|
.It Ar JTAGICE3
|
|
.It Ar Atmel-ICE
|
|
.It Ar Power Debugger
|
|
.It Ar PICkit 4
|
|
.It Ar MPLAB SNAP
|
|
.It Ar AVR Dragon
|
|
When using the JTAG ICE mkII, JTAGICE3, Atmel-ICE, PICkit 4, MPLAB SNAP,
|
|
Power Debugger or AVR Dragon in JTAG mode, the following extended parameter
|
|
is accepted:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar jtagchain=UB,UA,BB,BA
|
|
Setup the JTAG scan chain for
|
|
.Ar UB
|
|
units before,
|
|
.Ar UA
|
|
units after,
|
|
.Ar BB
|
|
bits before, and
|
|
.Ar BA
|
|
bits after the target AVR, respectively.
|
|
Each AVR unit within the chain shifts by 4 bits.
|
|
Other JTAG units might require a different bit shift count.
|
|
.El
|
|
.Pp
|
|
The PICkit 4 and the Power Debugger also supports high-voltage UPDI programming.
|
|
This is used to enable a UPDI pin that has previously been set to RESET or
|
|
GPIO mode. High-voltage UPDI can be utilized by using an extended parameter:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar hvupdi
|
|
Enable high-voltage UPDI initialization for targets that supports this.
|
|
.El
|
|
.It Ar AVR910
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar devcode=VALUE
|
|
Override the device code selection by using
|
|
.Ar VALUE
|
|
as the device code.
|
|
The programmer is not queried for the list of supported
|
|
device codes, and the specified
|
|
.Ar VALUE
|
|
is not verified but used directly within the
|
|
.Ql T
|
|
command sent to the programmer.
|
|
.Ar VALUE
|
|
can be specified using the conventional number notation of the
|
|
C programming language.
|
|
.El
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar no_blockmode
|
|
Disables the default checking for block transfer capability.
|
|
Use
|
|
.Ar no_blockmode
|
|
only if your
|
|
.Ar AVR910
|
|
programmer creates errors during initial sequence.
|
|
.El
|
|
.It Ar Arduino
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar attemps[=<1..99>]
|
|
Specify how many connection retry attemps to perform before exiting.
|
|
Defaults to 10 if not specified.
|
|
.El
|
|
.It Ar Urclock
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar showall
|
|
Show all info for the connected part, then exit. The -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.
|
|
.It Ar showid
|
|
Show a unique Urclock ID stored in either flash or EEPROM of the MCU, then exit.
|
|
.It Ar 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 -xid=<E|F>.<addr>.<len> extended parameter. E
|
|
stands for EEPROM and 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.
|
|
.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. 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>
|
|
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.
|
|
.It Ar showapp
|
|
Show the size of the programmed application, then exit.
|
|
.It Ar showstore
|
|
Show the size of the unused flash between the application and metadata, then exit.
|
|
.It Ar showmeta
|
|
Show the size of the metadata just below the bootloader, then exit.
|
|
.It Ar showboot
|
|
Show the size of the bootloader, then exit.
|
|
.It Ar showversion
|
|
Show bootloader version and capabilities, then exit.
|
|
.It Ar 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 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 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>
|
|
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.
|
|
.It Ar 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.
|
|
.It Ar 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.
|
|
.It Ar 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 -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.
|
|
.It Ar initstore
|
|
On writing to flash fill the store space between the flash application and
|
|
the metadata section with 0xff.
|
|
.It Ar nofilename
|
|
On writing to flash do not store the application input filename (nor a title).
|
|
.It Ar nodate
|
|
On writing to flash do not store the application input filename (nor a
|
|
title) and no date either.
|
|
.It Ar 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.
|
|
.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 120 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
|
|
.It Ar buspirate
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar reset={cs,aux,aux2}
|
|
The default setup assumes the BusPirate's CS output pin connected to
|
|
the RESET pin on AVR side. It is however possible to have multiple AVRs
|
|
connected to the same BP with SDI, SDO and SCK lines common for all of them.
|
|
In such a case one AVR should have its RESET connected to BusPirate's
|
|
.Pa CS
|
|
pin, second AVR's RESET connected to BusPirate's
|
|
.Pa AUX
|
|
pin and if your BusPirate has an
|
|
.Pa AUX2
|
|
pin (only available on BusPirate version v1a with firmware 3.0 or newer)
|
|
use that to activate RESET on the third AVR.
|
|
.Pp
|
|
It may be a good idea to decouple the BusPirate and the AVR's SPI buses from
|
|
each other using a 3-state bus buffer. For example 74HC125 or 74HC244 are some
|
|
good candidates with the latches driven by the appropriate reset pin (cs,
|
|
aux or aux2). Otherwise the SPI traffic in one active circuit may interfere
|
|
with programming the AVR in the other design.
|
|
.It Ar spifreq=<0..7>
|
|
The SPI speed for the Bus Pirate's binary SPI mode:
|
|
.Bd -literal
|
|
0 .. 30 kHz (default)
|
|
1 .. 125 kHz
|
|
2 .. 250 kHz
|
|
3 .. 1 MHz
|
|
4 .. 2 MHz
|
|
5 .. 2.6 MHz
|
|
6 .. 4 MHz
|
|
7 .. 8 MHz
|
|
.Ed
|
|
.It Ar rawfreq=<0..3>
|
|
Sets the SPI speed and uses the Bus Pirate's binary "raw-wire" mode:
|
|
.Bd -literal
|
|
0 .. 5 kHz
|
|
1 .. 50 kHz
|
|
2 .. 100 kHz (Firmware v4.2+ only)
|
|
3 .. 400 kHz (v4.2+)
|
|
.Ed
|
|
.Pp
|
|
The only advantage of the "raw-wire" mode is the different SPI frequencies
|
|
available. Paged writing is not implemented in this mode.
|
|
.It Ar ascii
|
|
Attempt to use ASCII mode even when the firmware supports BinMode (binary
|
|
mode).
|
|
BinMode is supported in firmware 2.7 and newer, older FW's either don't
|
|
have BinMode or their BinMode is buggy. ASCII mode is slower and makes
|
|
the above
|
|
.Ar reset= , spifreq=
|
|
and
|
|
.Ar rawfreq=
|
|
parameters unavailable. Be aware that ASCII mode is not guaranteed to work
|
|
with newer firmware versions, and is retained only to maintain compatibility
|
|
with older firmware versions.
|
|
.It Ar nopagedwrite
|
|
Firmware versions 5.10 and newer support a binary mode SPI command that enables
|
|
whole pages to be written to AVR flash memory at once, resulting in a
|
|
significant write speed increase. If use of this mode is not desirable for some
|
|
reason, this option disables it.
|
|
.It Ar nopagedread
|
|
Newer firmware versions support in binary mode SPI command some AVR Extended
|
|
Commands. Using the "Bulk Memory Read from Flash" results in a
|
|
significant read speed increase. If use of this mode is not desirable for some
|
|
reason, this option disables it.
|
|
.It Ar cpufreq=<125..4000>
|
|
This sets the AUX pin to output a frequency of
|
|
.Ar n
|
|
kHz. Connecting
|
|
the AUX pin to the XTAL1 pin of your MCU, you can provide it a clock,
|
|
for example when it needs an external clock because of wrong fuses settings.
|
|
Make sure the CPU frequency is at least four times the SPI frequency.
|
|
.It Ar serial_recv_timeout=<1...>
|
|
This sets the serial receive timeout to the given value.
|
|
The timeout happens every time avrdude waits for the BusPirate prompt.
|
|
Especially in ascii mode this happens very often, so setting a smaller value
|
|
can speed up programming a lot.
|
|
The default value is 100ms. Using 10ms might work in most cases.
|
|
.El
|
|
.It Ar Micronucleus bootloader
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar wait[=<timeout>]
|
|
If the device is not connected, wait for the device to be plugged in.
|
|
The optional
|
|
.Ar timeout
|
|
specifies the connection time-out in seconds.
|
|
If no time-out is specified, AVRDUDE will wait indefinitely until the
|
|
device is plugged in.
|
|
.El
|
|
.It Ar Teensy bootloader
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar wait[=<timeout>]
|
|
If the device is not connected, wait for the device to be plugged in.
|
|
The optional
|
|
.Ar timeout
|
|
specifies the connection time-out in seconds.
|
|
If no time-out is specified, AVRDUDE will wait indefinitely until the
|
|
device is plugged in.
|
|
.El
|
|
.It Ar Wiring
|
|
When using the Wiring programmer type, the
|
|
following optional extended parameter is accepted:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar snooze=<0..32767>
|
|
After performing the port open phase, AVRDUDE will wait/snooze for
|
|
.Ar snooze
|
|
milliseconds before continuing to the protocol sync phase.
|
|
No toggling of DTR/RTS is performed if
|
|
.Ar snooze
|
|
is greater than 0.
|
|
.El
|
|
.It Ar PICkit2
|
|
Connection to the PICkit2 programmer:
|
|
.Bd -literal
|
|
(AVR) (PICkit2)
|
|
RST - VPP/MCLR (1)
|
|
VDD - VDD Target (2) -- possibly optional if AVR self powered
|
|
GND - GND (3)
|
|
SDI - PGD (4)
|
|
SCLK - PDC (5)
|
|
SDO - AUX (6)
|
|
|
|
.Ed
|
|
Extended commandline parameters:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar clockrate=<rate>
|
|
Sets the SPI clocking rate in Hz (default is 100kHz). Alternately the -B or -i options can be used to set the period.
|
|
.It Ar timeout=<usb-transaction-timeout>
|
|
Sets the timeout for USB reads and writes in milliseconds (default is 1500 ms).
|
|
.El
|
|
.It Ar USBasp
|
|
Extended parameters:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar section_config
|
|
Programmer will erase configuration section with option
|
|
.Fl e
|
|
(chip erase), rather than entire chip.
|
|
Only applicable to TPI devices (ATtiny 4/5/9/10/20/40).
|
|
.El
|
|
.It Ar xbee
|
|
Extended parameters:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar xbeeresetpin=<1..7>
|
|
Select the XBee pin DIO<1..7> that is connected to the MCU's
|
|
.Ql /RESET
|
|
line. The programmer needs to know which DIO pin to use to reset into the
|
|
bootloader. The default (3) is the DIO3 pin (XBee pin 17), but some
|
|
commercial products use a different XBee pin.
|
|
.Pp
|
|
The remaining two necessary XBee-to-MCU connections are not selectable - the
|
|
XBee DOUT pin (pin 2) must be connected to the MCU's
|
|
.Ql RXD
|
|
line, and the XBee DIN pin (pin 3) must be connected to the MCU's
|
|
.Ql TXD
|
|
line.
|
|
.El
|
|
.It Ar STK500
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar attemps[=<1..99>]
|
|
Specify how many connection retry attemps to perform before exiting.
|
|
Defaults to 10 if not specified.
|
|
.El
|
|
.It Ar serialupdi
|
|
Extended parameters:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar rtsdtr=low|high
|
|
Forces RTS/DTR lines to assume low or high state during the whole
|
|
programming session. Some programmers might use this signal to
|
|
indicate UPDI programming state, but this is strictly hardware
|
|
specific.
|
|
.Pp
|
|
When not provided, driver/OS default value will be used.
|
|
.El
|
|
.It Ar linuxspi
|
|
Extended parameter:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar disable_no_cs
|
|
Ensures the programmer does not use the SPI_NO_CS bit for the SPI
|
|
driver. This parameter is useful for kernels that do not support
|
|
the CS line being managed outside the application.
|
|
.El
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -offset indent -width /dev/ppi0XXX
|
|
.It Pa /dev/ppi0
|
|
Default device to be used for communication with the programming
|
|
hardware
|
|
.It Pa avrdude.conf
|
|
Programmer and parts configuration file
|
|
.Pp
|
|
On Windows systems, this file is looked up in the same directory as the
|
|
executable file.
|
|
On all other systems, the file is first looked up in
|
|
.Pa ../etc/ ,
|
|
relative to the path of the executable, then in the same directory as
|
|
the executable itself, and finally in the system default location
|
|
.Pa ${PREFIX}/etc/avrdude.conf .
|
|
.It Pa ${XDG_CONFIG_HOME}/avrdude/avrdude.rc
|
|
Local programmer and parts configuration file (per-user overrides); it follows the same syntax as
|
|
.Pa avrdude.conf ;
|
|
if the
|
|
.Pa ${XDG_CONFIG_HOME}
|
|
environment variable is not set or empty, the directory
|
|
.Pa ${HOME}/.config/
|
|
is used instead.
|
|
.It Pa ${HOME}/.avrduderc
|
|
Alternative location of the per-user configuration file if above file does not exist
|
|
.It Pa ~/.inputrc
|
|
Initialization file for the
|
|
.Xr readline 3
|
|
library
|
|
.It Pa <prefix>/doc/avrdude/avrdude.pdf
|
|
User manual
|
|
.El
|
|
.\" .Sh EXAMPLES
|
|
.Sh DIAGNOSTICS
|
|
.Bd -literal
|
|
avrdude: jtagmkII_setparm(): bad response to set parameter command: RSP_FAILED
|
|
avrdude: jtagmkII_getsync(): ISP activation failed, trying debugWire
|
|
avrdude: Target prepared for ISP, signed off.
|
|
avrdude: Please restart avrdude without power-cycling the target.
|
|
.Ed
|
|
.Pp
|
|
If the target AVR has been set up for debugWire mode (i. e. the
|
|
.Em DWEN
|
|
fuse is programmed), normal ISP connection attempts will fail as
|
|
the
|
|
.Em /RESET
|
|
pin is not available.
|
|
When using the JTAG ICE mkII in ISP mode, the message shown indicates
|
|
that
|
|
.Nm
|
|
has guessed this condition, and tried to initiate a debugWire reset
|
|
to the target.
|
|
When successful, this will leave the target AVR in a state where it
|
|
can respond to normal ISP communication again (until the next power
|
|
cycle).
|
|
Typically, the same command is going to be retried again immediately
|
|
afterwards, and will then succeed connecting to the target using
|
|
normal ISP communication.
|
|
.Sh SEE ALSO
|
|
.Xr avr-objcopy 1 ,
|
|
.Xr ppi 4 ,
|
|
.Xr libelf 3,
|
|
.Xr readline 3
|
|
.Pp
|
|
The AVR microcontroller product description can be found at
|
|
.Pp
|
|
.Dl "http://www.atmel.com/products/AVR/"
|
|
.\" .Sh HISTORY
|
|
.Sh AUTHORS
|
|
.Nm Avrdude
|
|
was written by Brian S. Dean <bsd@bsdhome.com>.
|
|
.Pp
|
|
This man page by
|
|
.ie t J\(:org Wunsch.
|
|
.el Joerg Wunsch.
|
|
.Sh BUGS
|
|
Please report bugs via
|
|
.Dl "https://github.com/avrdudes/avrdude/issues"
|
|
.Pp
|
|
The JTAG ICE programmers currently cannot write to the flash ROM
|
|
one byte at a time.
|
|
For that reason, updating the flash ROM from terminal mode does not
|
|
work.
|
|
.Pp
|
|
Page-mode programming the EEPROM through JTAG (i.e. through an
|
|
.Fl U
|
|
option) requires a prior chip erase.
|
|
This is an inherent feature of the way JTAG EEPROM programming works.
|
|
This also applies to the STK500 and STK600 in parallel programming mode.
|
|
.Pp
|
|
The USBasp and USBtinyISP drivers do not offer any option to distinguish multiple
|
|
devices connected simultaneously, so effectively only a single device
|
|
is supported.
|
|
.Pp
|
|
Chip Select must be externally held low for direct SPI when
|
|
using USBtinyISP, and send must be a multiple of four bytes.
|
|
.Pp
|
|
The avrftdi driver allows one to select specific devices using any combination of vid,pid
|
|
serial number (usbsn) vendor description (usbvendoror part description (usbproduct)
|
|
as seen with lsusb or whatever tool used to view USB device information. Multiple
|
|
devices can be on the bus at the same time. For the H parts, which have multiple MPSSE
|
|
interfaces, the interface can also be selected. It defaults to interface 'A'.
|