549 lines
16 KiB
Groff
549 lines
16 KiB
Groff
.\"
|
|
.\" avrdude - A Downloader/Uploader for AVR device programmers
|
|
.\" Copyright (C) 2001, 2002, 2003 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, write to the Free Software
|
|
.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
.\"
|
|
.\"
|
|
.\" $Id$
|
|
.\"
|
|
.Dd DATE July 24, 2003
|
|
.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 c Ar programmer-id
|
|
.Op Fl C Ar config-file
|
|
.Op Fl D
|
|
.Op Fl e
|
|
.Oo Fl E Ar exitspec Ns
|
|
.Op \&, Ns Ar exitspec
|
|
.Oc
|
|
.Op Fl f Ar format
|
|
.Op Fl F
|
|
.Op Fl i Ar filename
|
|
.Op Fl m Ar memtype
|
|
.Op Fl o Ar filename
|
|
.Op Fl n
|
|
.Op Fl P Ar port
|
|
.Op Fl q
|
|
.Op Fl t
|
|
.Op Fl U Ar memtype:op:filename:filefmt
|
|
.Op Fl v
|
|
.Op Fl V
|
|
.Op Fl y
|
|
.Op Fl Y
|
|
.Sh DESCRIPTION
|
|
.Nm Avrdude
|
|
is a program for downloading code and data to Atmel AVR
|
|
microcontrollers.
|
|
.Nm Avrdude
|
|
supports Atmel's STK500 programmer as well as a simple hard-wired
|
|
programmer connected directly to a
|
|
.Xr ppi 4
|
|
parallel 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 MISO
|
|
and
|
|
.Ql MOSI
|
|
need to be connected to the parallel port. 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
|
|
standalone 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
|
|
See the file
|
|
.Pa ${PREFIX}/share/doc/avrdude/avrdude.pdf
|
|
for a schematic of the
|
|
.Xr ppi 4
|
|
based programming hardware.
|
|
.Pp
|
|
Atmel's STK500 programmer is also supported and connects to a serial
|
|
port.
|
|
.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
|
|
.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 seperate memory types and can be programmed using data from a file
|
|
(see the
|
|
.Fl m
|
|
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 programmer, several operational parameters (target supply
|
|
voltage, target Aref voltage, master 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 is the only option that is mandatory for every invocation of
|
|
.Nm avrdude .
|
|
It specifies the type of the MCU connected to the programmer. These are read from the config file. If
|
|
.Nm avrdude
|
|
does not know about a part that you have, simply add it to the config
|
|
file (be sure and submit a patch back to the author so that it can be
|
|
incorporated for the next version). See the sample config file for
|
|
the format. Currently, the following MCU types are understood:
|
|
.Pp
|
|
.TS
|
|
ll.
|
|
\fBOption tag\fP \fBOfficial part name\fP
|
|
t15 ATtiny15
|
|
1200 AT90S1200
|
|
2313 AT90S2313
|
|
2333 AT90S2333
|
|
2343 AT90S2343 (*)
|
|
4414 AT90S4414
|
|
4433 AT90S4433
|
|
4434 AT90S4434
|
|
8515 AT90S8515
|
|
8535 AT90S8535
|
|
m163 ATMEGA163
|
|
m169 ATMEGA169
|
|
m128 ATMEGA128
|
|
m103 ATMEGA103
|
|
m16 ATMEGA16
|
|
m8 ATMEGA8
|
|
.TE
|
|
.Bl -tag -width "(*) "
|
|
.It "(*)"
|
|
The AT90S2323 uses the same algorithm.
|
|
.El
|
|
.It Fl c Ar programmer-id
|
|
Use the pin configuration specified by the argument. 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}/.avrduderc
|
|
file to assign a default programmer to keep from having to specify
|
|
this option on every invocation.
|
|
.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. If you have a programmer or part that
|
|
.Nm avrdude
|
|
does not know about, you can add it to the config file (be sure and
|
|
submit a patch back to the author so that it can be incorporated for
|
|
the next version). See the config file, located at
|
|
.Pa ${PREFIX}/etc/avrdude.conf ,
|
|
which contains a description of the format.
|
|
.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.
|
|
However, to remain backward compatible, the
|
|
.Fl i ,
|
|
and
|
|
.Fl m
|
|
options automatically disable the auto erase feature.
|
|
.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 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 EERPOM 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.
|
|
.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.
|
|
.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.
|
|
.El
|
|
.Pp
|
|
Multiple
|
|
.Ar exitspec
|
|
arguments can be separated with commas.
|
|
.It Fl f Ar format
|
|
(Deprecated, use
|
|
.Fl U
|
|
instead.) This option specifies the file format for the input or
|
|
output files to be processed.
|
|
.Ar Format
|
|
can be one of:
|
|
.Bl -tag -width sss
|
|
.It Ar i
|
|
Intel Hex
|
|
.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 m
|
|
immediate; actual byte values specified on the command line, seperated
|
|
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 .
|
|
.El
|
|
.Pp
|
|
The default is to use auto detection for input files, and raw binary
|
|
format for output files.
|
|
.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.
|
|
.It Fl i Ar filename
|
|
(Deprecated, use
|
|
.Fl U
|
|
instead.) Specifies the input file to be programmed into the MCU.
|
|
Can be specified as
|
|
.Ql \&-
|
|
to use
|
|
.Em stdin
|
|
as the input.
|
|
.It Fl I Ar data
|
|
(Deprecated, use
|
|
.Fl U
|
|
instead.) Same as specifying
|
|
.Fl i
|
|
and
|
|
.Fl f Ar m
|
|
together, i.e., this is a shortcut for using immediate file input mode
|
|
where the filename field is used as the data itself. Useful for
|
|
programming single byte memories such as fuse bytes without having to
|
|
use single byte files or enter interactive terminal mode.
|
|
.It Fl m Ar memtype
|
|
(Deprecated, use
|
|
.Fl U
|
|
instead.) Specifies which program area of the MCU to read or write;
|
|
allowable values depend on the MCU being programmed, but most support
|
|
at least
|
|
.Em eeprom
|
|
for the EEPROM, and
|
|
.Em flash
|
|
for the flash ROM. Use the
|
|
.Fl v
|
|
option on the command line or the
|
|
.Ar part
|
|
command from terminal mode to display all the memory types supported
|
|
by a particular device. The default is
|
|
.Em flash .
|
|
.It Fl n
|
|
No-write - disables actually writing data to the MCU (useful for debugging
|
|
.Nm avrdude
|
|
).
|
|
.It Fl o Ar filename
|
|
(Deprecated, use
|
|
.Fl U
|
|
instead.) Specifies the name of the output file to write, and causes
|
|
the respective memory area to be read from the MCU. Can be specified
|
|
as
|
|
.Ql \&-
|
|
to write to
|
|
.Em stdout .
|
|
.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.
|
|
.It Fl q
|
|
Disable (or quell) output of the progress bar while reading or writing
|
|
to the device.
|
|
.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
|
|
.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. See the
|
|
.Fl f
|
|
option for possible values.
|
|
.It Fl v
|
|
Enable verbose output.
|
|
.It Fl V
|
|
Disable automatic verify check when uploading data.
|
|
.It Fl y
|
|
Tells
|
|
.Nm
|
|
to use the last four bytes of the connected parts' EEPROM memory to
|
|
track the number of times the device has been erased. When this
|
|
option is used and the
|
|
.Fl e
|
|
flag is specified to generate a chip erase, the previous counter will
|
|
be saved before the chip erase, it is then incremented, and written
|
|
back after the erase cycle completes. Presumably, the device would
|
|
only be erased just before being programmed, and thus, this can be
|
|
utilized to give an indication of how many erase-rewrite cycles the
|
|
part has undergone. Since the FLASH memory can only endure a finite
|
|
number of erase-rewrite cycles, one can use this option to track when
|
|
a part is nearing the limit. The typical limit for Atmel AVR FLASH is
|
|
1000 cycles. Of course, if the application needs the last four bytes
|
|
of EEPROM memory, this option should not be used.
|
|
.It Fl Y Ar cycles
|
|
Instructs
|
|
.Nm
|
|
to initialize the erase-rewrite cycle counter residing at the last four
|
|
bytes of EEPROM memory to the specified value. If the application
|
|
needs the last four bytes of EEPROM memory, this option should not be
|
|
used.
|
|
.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:
|
|
.Bl -tag -offset indent -width indent
|
|
.It Ar dump memtype addr nbytes
|
|
Read
|
|
.Ar nbytes
|
|
bytes from the specified memory area, and display them in the usual
|
|
hexadecimal and ASCII form.
|
|
.It Ar dump
|
|
Continue dumping the memory contents for another
|
|
.Ar nbytes
|
|
where the previous
|
|
.Ar dump
|
|
command left off.
|
|
.It Ar write memtype addr byte1 ... byteN
|
|
Manually program the respective memory cells, starting at address
|
|
.Ar addr ,
|
|
using the values
|
|
.Ar byte1
|
|
through
|
|
.Ar byteN .
|
|
This feature is not implemented for bank-addressed memories such as
|
|
the flash memory of ATMega devices.
|
|
.It Ar erase
|
|
Perform a chip erase.
|
|
.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.
|
|
.It Ar sig
|
|
Display the device signature bytes.
|
|
.It Ar part
|
|
Display the current part settings.
|
|
.It Ar vtarg voltage
|
|
Set the target's supply voltage to
|
|
.Ar voltage
|
|
Volts.
|
|
.Em Only supported on the STK500 programmer.
|
|
.It Ar varef 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.
|
|
.Em Only supported on the STK500 programmer.
|
|
.It Ar fosc freq Ns Op M Ns \&| Ns k
|
|
Set the master oscillator to
|
|
.Ar freq
|
|
Hz.
|
|
An optional trailing letter
|
|
.Ar \&M
|
|
multiplies by 1E6, a trailing letter
|
|
.Ar \&k
|
|
by 1E3.
|
|
.Em Only supported on the STK500 programmer.
|
|
.It Ar fosc off
|
|
Turn the master oscillator off.
|
|
.Em Only supported on the STK500 programmer.
|
|
.It Ar parms
|
|
Display the current voltage and master oscillator parameters.
|
|
.Em Only supported on the STK500 programmer.
|
|
.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
|
|
.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 MOSI (to MCU)
|
|
10 MISO (from MCU)
|
|
18-25 GND
|
|
.TE
|
|
.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 ${PREFIX}/etc/avrdude.conf
|
|
programmer and parts configuration file
|
|
.It Pa ${HOME}/.avrduderc
|
|
programmer and parts configuration file (per-user overrides)
|
|
.It Pa ~/.inputrc
|
|
Initialization file for the
|
|
.Xr readline 3
|
|
library
|
|
.It Pa ${PREFIX}/share/doc/avrdude/avrdude.pdf
|
|
Schematic of programming hardware
|
|
.El
|
|
.\" .Sh EXAMPLES
|
|
.\" .Sh DIAGNOSTICS
|
|
.Sh SEE ALSO
|
|
.Xr avr-objcopy 1 ,
|
|
.Xr ppi 4 ,
|
|
.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 to avrdude-dev@nongnu.org.
|