source: arduino-1-6-7/trunk/fuentes/arduino-ide-amd64/hardware/tools/avr/share/man/man1/avrdude.1 @ 4837

Last change on this file since 4837 was 4837, checked in by daduve, 3 years ago

Adding new version

File size: 38.4 KB
Line 
1.\"
2.\" avrdude - A Downloader/Uploader for AVR device programmers
3.\" Copyright (C) 2001, 2002, 2003, 2005 - 2016  Joerg Wunsch
4.\"
5.\" This program is free software; you can redistribute it and/or modify
6.\" it under the terms of the GNU General Public License as published by
7.\" the Free Software Foundation; either version 2 of the License, or
8.\" (at your option) any later version.
9.\"
10.\" This program is distributed in the hope that it will be useful,
11.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13.\" GNU General Public License for more details.
14.\"
15.\" You should have received a copy of the GNU General Public License
16.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
17.\"
18.\"
19.\" $Id: avrdude.1 1375 2016-02-15 21:02:00Z joerg_wunsch $
20.\"
21.Dd DATE February 15, 2016
22.Os
23.Dt AVRDUDE 1
24.Sh NAME
25.Nm avrdude
26.Nd driver program for ``simple'' Atmel AVR MCU programmer
27.Sh SYNOPSIS
28.Nm
29.Fl p Ar partno
30.Op Fl b Ar baudrate
31.Op Fl B Ar bitclock
32.Op Fl c Ar programmer-id
33.Op Fl C Ar config-file
34.Op Fl D
35.Op Fl e
36.Oo Fl E Ar exitspec Ns
37.Op \&, Ns Ar exitspec
38.Oc
39.Op Fl F
40.Op Fl i Ar delay
41.Op Fl n logfile
42.Op Fl n
43.Op Fl O
44.Op Fl P Ar port
45.Op Fl q
46.Op Fl s
47.Op Fl t
48.Op Fl u
49.Op Fl U Ar memtype:op:filename:filefmt
50.Op Fl v
51.Op Fl x Ar extended_param
52.Op Fl V
53.Sh DESCRIPTION
54.Nm Avrdude
55is a program for downloading code and data to Atmel AVR
56microcontrollers.
57.Nm Avrdude
58supports Atmel's STK500 programmer,
59Atmel's AVRISP and AVRISP mkII devices,
60Atmel's STK600,
61Atmel's JTAG ICE (mkI, mkII and 3, the latter two also in ISP mode),
62programmers complying to AppNote AVR910 and AVR109 (including the Butterfly),
63as well as a simple hard-wired
64programmer connected directly to a
65.Xr ppi 4
66or
67.Xr parport 4
68parallel port, or to a standard serial port.
69In the simplest case, the hardware consists just of a
70cable connecting the respective AVR signal lines to the parallel port.
71.Pp
72The MCU is programmed in
73.Em serial programming mode ,
74so, for the
75.Xr ppi 4
76based programmer, the MCU signals
77.Ql /RESET ,
78.Ql SCK ,
79.Ql MISO
80and
81.Ql MOSI
82need to be connected to the parallel port.  Optionally, some otherwise
83unused output pins of the parallel port can be used to supply power
84for the MCU part, so it is also possible to construct a passive
85stand-alone programming device.  Some status LEDs indicating the
86current operating state of the programmer can be connected, and a
87signal is available to control a buffer/driver IC 74LS367 (or
8874HCT367).  The latter can be useful to decouple the parallel port
89from the MCU when in-system programming is used.
90.Pp
91A number of equally simple bit-bang programming adapters that connect
92to a serial port are supported as well, among them the popular
93Ponyprog serial adapter, and the DASA and DASA3 adapters that used to
94be supported by uisp(1).
95Note that these adapters are meant to be attached to a physical serial
96port.
97Connecting to a serial port emulated on top of USB is likely to not
98work at all, or to work abysmally slow.
99.Pp
100If you happen to have a Linux system with at least 4 hardware GPIOs
101available (like almost all embedded Linux boards) you can do without
102any additional hardware - just connect them to the MOSI, MISO, RESET
103and SCK pins on the AVR and use the linuxgpio programmer type. It bitbangs
104the lines using the Linux sysfs GPIO interface. Of course, care should
105be taken about voltage level compatibility. Also, although not strictrly
106required, it is strongly advisable to protect the GPIO pins from
107overcurrent situations in some way. The simplest would be to just put
108some resistors in series or better yet use a 3-state buffer driver like
109the 74HC244. Have a look at http://kolev.info/avrdude-linuxgpio for a more
110detailed tutorial about using this programmer type.
111.Pp
112Atmel's STK500 programmer is also supported and connects to a serial
113port.
114Both, firmware versions 1.x and 2.x can be handled, but require a
115different programmer type specification (by now).
116Using firmware version 2, high-voltage programming is also supported,
117both parallel and serial
118(programmer types stk500pp and stk500hvsp).
119.Pp
120Wiring boards are supported, utilizing STK500 V2.x protocol, but
121a simple DTR/RTS toggle is used to set the boards into programming mode.
122The programmer type is ``wiring''.
123.Pp
124The Arduino (which is very similar to the STK500 1.x) is supported via
125its own programmer type specification ``arduino''.
126.Pp
127The BusPirate is a versatile tool that can also be used as an AVR programmer.
128A single BusPirate can be connected to up to 3 independent AVRs. See
129the section on
130.Em extended parameters
131below for details.
132.Pp
133Atmel's STK600 programmer is supported in ISP and high-voltage
134programming modes, and connects through the USB.
135For ATxmega devices, the STK600 is supported in PDI mode.
136For ATtiny4/5/9/10 devices, the STK600 and AVRISP mkII are supported in TPI mode.
137.Pp
138The simple serial programmer described in Atmel's application note
139AVR910, and the bootloader described in Atmel's application note
140AVR109 (which is also used by the AVR Butterfly evaluation board), are
141supported on a serial port.
142.Pp
143Atmel's JTAG ICE (mkI, mkII, and 3) is supported as well to up- or download memory
144areas from/to an AVR target (no support for on-chip debugging).
145For the JTAG ICE mkII, JTAG, debugWire and ISP mode are supported, provided
146it has a firmware revision of at least 4.14 (decimal).
147JTAGICE3 also supports all of JTAG, debugWIRE, and ISP mode.
148See below for the limitations of debugWire.
149For ATxmega devices, the JTAG ICE mkII is supported in PDI mode, provided it
150has a revision 1 hardware and firmware version of at least 5.37 (decimal).
151For ATxmega devices, the JTAGICE3 is supported in PDI mode.
152.Pp
153Atmel-ICE (ARM/AVR) is supported in all modes (JTAG, PDI for Xmega, debugWIRE,
154ISP).
155.Pp
156Atmel's XplainedPro boards, using the EDBG protocol (CMSIS-DAP compatible),
157are supported using the "jtag3" programmer type.
158.Pp
159Atmel's XplainedMini boards, using the mEDBG protocol,
160are also supported using the "jtag3" programmer type.
161.Pp
162The AVR Dragon is supported in all modes (ISP, JTAG, HVSP, PP, debugWire).
163When used in JTAG and debugWire mode, the AVR Dragon behaves similar to a
164JTAG ICE mkII, so all device-specific comments for that device
165will apply as well.
166When used in ISP mode, the AVR Dragon behaves similar to an
167AVRISP mkII (or JTAG ICE mkII in ISP mode), so all device-specific
168comments will apply there.
169In particular, the Dragon starts out with a rather fast ISP clock
170frequency, so the
171.Fl B Ar bitclock
172option might be required to achieve a stable ISP communication.
173For ATxmega devices, the AVR Dragon is supported in PDI mode, provided it
174has a firmware version of at least 6.11 (decimal).
175.Pp
176The avrftdi, USBasp ISP and USBtinyISP adapters are also supported, provided
177.Nm avrdude
178has been compiled with libusb support.
179USBasp ISP and USBtinyISP both feature simple firmware-only USB implementations,
180running on an ATmega8 (or ATmega88), or ATtiny2313, respectively. If libftdi has
181has been compiled in
182.Nm avrdude ,
183the avrftdi device adds support for many programmers using FTDI's 2232C/D/H
184and 4232H parts running in MPSSE mode, which hard-codes (in the chip)
185SCK to bit 1, MOSI to bit 2, and MISO to bit 3. Reset is usually bit 4.
186.Pp
187The Atmel DFU bootloader is supported in both, FLIP protocol version 1
188(AT90USB* and ATmega*U* devices), as well as version 2 (Xmega devices).
189See below for some hints about FLIP version 1 protocol behaviour.
190.Pp
191Input files can be provided, and output files can be written in
192different file formats, such as raw binary files containing the data
193to download to the chip, Intel hex format, or Motorola S-record
194format.  There are a number of tools available to produce those files,
195like
196.Xr asl 1
197as a standalone assembler, or
198.Xr avr-objcopy 1
199for the final stage of the GNU toolchain for the AVR microcontroller.
200.Pp
201Provided
202.Xr libelf 3
203was present when compiling
204.Nm avrdude ,
205the input file can also be the final ELF file as produced by the linker.
206The appropriate ELF section(s) will be examined, according to the memory
207area to write to.
208.Pp
209.Nm Avrdude
210can program the EEPROM and flash ROM memory cells of supported AVR
211parts.  Where supported by the serial instruction set, fuse bits and
212lock bits can be programmed as well.  These are implemented within
213.Nm
214as separate memory types and can be programmed using data from a file
215(see the
216.Fl m
217option) or from terminal mode (see the
218.Ar dump
219and
220.Ar write
221commands).  It is also possible to read the chip (provided it has not
222been code-protected previously, of course) and store the data in a
223file.  Finally, a ``terminal'' mode is available that allows one to
224interactively communicate with the MCU, and to display or program
225individual memory cells.
226On the STK500 and STK600 programmer, several operational parameters (target supply
227voltage, target Aref voltage, master clock) can be examined and changed
228from within terminal mode as well.
229.Ss Options
230In order to control all the different operation modi, a number of options
231need to be specified to
232.Nm avrdude .
233.Bl -tag -offset indent -width indent
234.It Fl p Ar partno
235This is the only option that is mandatory for every invocation of
236.Nm avrdude .
237It specifies the type of the MCU connected to the programmer.  These are read from the config file.
238For currently supported MCU types use ? as partno, this will print a list of partno ids and official part names on the terminal. (Both can be used with the -p option.)
239.Pp
240Following parts need special attention:
241.Bl -tag -width "ATmega1234"
242.It "AT90S1200"
243The ISP programming protocol of the AT90S1200 differs in subtle ways
244from that of other AVRs.  Thus, not all programmers support this
245device.  Known to work are all direct bitbang programmers, and all
246programmers talking the STK500v2 protocol.
247.It "AT90S2343"
248The AT90S2323 and ATtiny22 use the same algorithm.
249.It "ATmega2560, ATmega2561"
250Flash addressing above 128 KB is not supported by all
251programming hardware.  Known to work are jtag2, stk500v2,
252and bit-bang programmers.
253.It "ATtiny11"
254The ATtiny11 can only be
255programmed in high-voltage serial mode.
256.El
257.It Fl b Ar baudrate
258Override the RS-232 connection baud rate specified in the respective
259programmer's entry of the configuration file.
260.It Fl B Ar bitclock
261Specify the bit clock period for the JTAG interface or the ISP clock (JTAG ICE only).
262The value is a floating-point number in microseconds.
263Alternatively, the value might be suffixed with "Hz", "kHz", or "MHz",
264in order to specify the bit clock frequency, rather than a period.
265The default value of the JTAG ICE results in about 1 microsecond bit
266clock period, suitable for target MCUs running at 4 MHz clock and
267above.
268Unlike certain parameters in the STK500, the JTAG ICE resets all its
269parameters to default values when the programming software signs
270off from the ICE, so for MCUs running at lower clock speeds, this
271parameter must be specified on the command-line.
272You can use the 'default_bitclock' keyword in your
273.Pa ${HOME}/.avrduderc
274file to assign a default value to keep from having to specify this
275option on every invocation.
276.It Fl c Ar programmer-id
277Use the programmer specified by the argument.  Programmers and their pin
278configurations are read from the config file (see the
279.Fl C
280option).  New pin configurations can be easily added or modified
281through the use of a config file to make
282.Nm avrdude
283work with different programmers as long as the programmer supports the
284Atmel AVR serial program method.  You can use the 'default_programmer'
285keyword in your
286.Pa ${HOME}/.avrduderc
287file to assign a default programmer to keep from having to specify
288this option on every invocation.
289A full list of all supported programmers is output to the terminal
290by using ? as programmer-id.
291.It Fl C Ar config-file
292Use the specified config file to load configuration data.  This file
293contains all programmer and part definitions that
294.Nm avrdude
295knows about.
296See the config file, located at
297.Pa ${PREFIX}/etc/avrdude.conf ,
298which contains a description of the format.
299.Pp
300If
301.Ar config-file
302is written as
303.Pa +filename
304then this file is read after the system wide and user configuration
305files. This can be used to add entries to the configuration
306without patching your system wide configuration file. It can be used
307several times, the files are read in same order as given on the command
308line.
309.It Fl D
310Disable auto erase for flash.  When the
311.Fl U
312option with flash memory is specified,
313.Nm
314will perform a chip erase before starting any of the programming
315operations, since it generally is a mistake to program the flash
316without performing an erase first.  This option disables that.
317Auto erase is not used for ATxmega devices as these devices can
318use page erase before writing each page so no explicit chip erase
319is required.
320Note however that any page not affected by the current operation
321will retain its previous contents.
322.It Fl e
323Causes a chip erase to be executed.  This will reset the contents of the
324flash ROM and EEPROM to the value
325.Ql 0xff ,
326and clear all lock bits.
327Except for ATxmega devices which can use page erase,
328it is basically a prerequisite command before the flash ROM can be
329reprogrammed again.  The only exception would be if the new
330contents would exclusively cause bits to be programmed from the value
331.Ql 1
332to
333.Ql 0 .
334Note that in order to reprogram EERPOM cells, no explicit prior chip
335erase is required since the MCU provides an auto-erase cycle in that
336case before programming the cell.
337.It Xo Fl E Ar exitspec Ns
338.Op \&, Ns Ar exitspec
339.Xc
340By default,
341.Nm
342leaves the parallel port in the same state at exit as it has been
343found at startup.  This option modifies the state of the
344.Ql /RESET
345and
346.Ql Vcc
347lines the parallel port is left at, according to the
348.Ar exitspec
349arguments provided, as follows:
350.Bl -tag -width noreset
351.It Ar reset
352The
353.Ql /RESET
354signal will be left activated at program exit, that is it will be held
355.Em low ,
356in order to keep the MCU in reset state afterwards.  Note in particular
357that the programming algorithm for the AT90S1200 device mandates that
358the
359.Ql /RESET
360signal is active
361.Em before
362powering up the MCU, so in case an external power supply is used for this
363MCU type, a previous invocation of
364.Nm
365with this option specified is one of the possible ways to guarantee this
366condition.
367.It Ar noreset
368The
369.Ql /RESET
370line will be deactivated at program exit, thus allowing the MCU target
371program to run while the programming hardware remains connected.
372.It Ar vcc
373This option will leave those parallel port pins active
374.Pq \&i. \&e. Em high
375that can be used to supply
376.Ql Vcc
377power to the MCU.
378.It Ar novcc
379This option will pull the
380.Ql Vcc
381pins of the parallel port down at program exit.
382.It Ar d_high
383This option will leave the 8 data pins on the parallel port active.
384.Pq \&i. \&e. Em high
385.It Ar d_low
386This option will leave the 8 data pins on the parallel port inactive.
387.Pq \&i. \&e. Em low
388.El
389.Pp
390Multiple
391.Ar exitspec
392arguments can be separated with commas.
393.It Fl F
394Normally,
395.Nm
396tries to verify that the device signature read from the part is
397reasonable before continuing.  Since it can happen from time to time
398that a device has a broken (erased or overwritten) device signature
399but is otherwise operating normally, this options is provided to
400override the check.
401Also, for programmers like the Atmel STK500 and STK600 which can
402adjust parameters local to the programming tool (independent of an
403actual connection to a target controller), this option can be used
404together with
405.Fl t
406to continue in terminal mode.
407.It Fl i Ar delay
408For bitbang-type programmers, delay for approximately
409.Ar delay
410microseconds between each bit state change.
411If the host system is very fast, or the target runs off a slow clock
412(like a 32 kHz crystal, or the 128 kHz internal RC oscillator), this
413can become necessary to satisfy the requirement that the ISP clock
414frequency must not be higher than 1/4 of the CPU clock frequency.
415This is implemented as a spin-loop delay to allow even for very
416short delays.
417On Unix-style operating systems, the spin loop is initially calibrated
418against a system timer, so the number of microseconds might be rather
419realistic, assuming a constant system load while
420.Nm
421is running.
422On Win32 operating systems, a preconfigured number of cycles per
423microsecond is assumed that might be off a bit for very fast or very
424slow machines.
425.It Fl l Ar logfile
426Use
427.Ar logfile
428rather than
429.Va stderr
430for diagnostics output.
431Note that initial diagnostic messages (during option parsing) are still
432written to
433.Va stderr
434anyway.
435.It Fl n
436No-write - disables actually writing data to the MCU (useful for debugging
437.Nm avrdude
438).
439.It Fl O
440Perform a RC oscillator run-time calibration according to Atmel
441application note AVR053.
442This is only supported on the STK500v2, AVRISP mkII, and JTAG ICE mkII
443hardware.
444Note that the result will be stored in the EEPROM cell at address 0.
445.It Fl P Ar port
446Use
447.Ar port
448to identify the device to which the programmer is attached.  By
449default the
450.Pa /dev/ppi0
451port is used, but if the programmer type normally connects to the
452serial port, the
453.Pa /dev/cuaa0
454port is the default.  If you need to use a different parallel or
455serial port, use this option to specify the alternate port name.
456.Pp
457On Win32 operating systems, the parallel ports are referred to as lpt1
458through lpt3, referring to the addresses 0x378, 0x278, and 0x3BC,
459respectively.  If the parallel port can be accessed through a different
460address, this address can be specified directly, using the common C
461language notation (i. e., hexadecimal values are prefixed by
462.Ql 0x
463).
464.Pp
465For the JTAG ICE mkII and JTAGICE3, if
466.Nm
467has been configured with libusb support,
468.Ar port
469can alternatively be specified as
470.Pa usb Ns Op \&: Ns Ar serialno .
471This will cause
472.Nm
473to search the programmer on USB.
474If
475.Ar serialno
476is also specified, it will be matched against the serial number read
477from any JTAG ICE mkII found on USB.
478The match is done after stripping any existing colons from the given
479serial number, and right-to-left, so only the least significant bytes
480from the serial number need to be given.
481.Pp
482As the AVRISP mkII device can only be talked to over USB, the very
483same method of specifying the port is required there.
484.Pp
485For the USB programmer "AVR-Doper" running in HID mode, the port must
486be specified as
487.Ar avrdoper.
488Libusb support is required on Unix but not on Windows. For more
489information about AVR-Doper see http://www.obdev.at/avrusb/avrdoper.html.
490.Pp
491For the USBtinyISP, which is a simplicistic device not implementing
492serial numbers, multiple devices can be distinguished by their
493location in the USB hierarchy.  See the the respective
494.Em Troubleshooting
495entry in the detailed documentation for examples.
496.Pp
497For programmers that attach to a serial port using some kind of
498higher level protocol (as opposed to bit-bang style programmers),
499.Ar port
500can be specified as
501.Pa net Ns \&: Ns Ar host Ns \&: Ns Ar port .
502In this case, instead of trying to open a local device, a TCP
503network connection to (TCP)
504.Ar port
505on
506.Ar host
507is established.
508The remote endpoint is assumed to be a terminal or console server
509that connects the network stream to a local serial port where the
510actual programmer has been attached to.
511The port is assumed to be properly configured, for example using a
512transparent 8-bit data connection without parity at 115200 Baud
513for a STK500.
514.It Fl q
515Disable (or quell) output of the progress bar while reading or writing
516to the device.  Specify it a second time for even quieter operation.
517.It Fl s
518Disable safemode prompting.  When safemode discovers that one or more
519fuse bits have unintentionally changed, it will prompt for
520confirmation regarding whether or not it should attempt to recover the
521fuse bit(s).  Specifying this flag disables the prompt and assumes
522that the fuse bit(s) should be recovered without asking for
523confirmation first.
524.It Fl t
525Tells
526.Nm
527to enter the interactive ``terminal'' mode instead of up- or downloading
528files.  See below for a detailed description of the terminal mode.
529.It Fl u
530Disable the safemode fuse bit checks.  Safemode is enabled by default
531and is intended to prevent unintentional fuse bit changes.  When
532enabled, safemode will issue a warning if the any fuse bits are found
533to be different at program exit than they were when
534.Nm
535was invoked.  Safemode won't alter fuse bits itself, but rather will
536prompt for instructions, unless the terminal is non-interactive, in
537which case safemode is disabled.  See the
538.Fl s
539option to disable safemode prompting.
540.Pp
541If one of the configuration files has a line
542.Dl "default_safemode = no;"
543safemode is disabled by default.
544The
545.Fl u
546option's effect is negated in that case, i. e. it
547.Em enables
548safemode.
549.Pp
550Safemode is always disabled for AVR32, Xmega and TPI devices.
551.It Xo Fl U Ar memtype Ns
552.Ar \&: Ns Ar op Ns
553.Ar \&: Ns Ar filename Ns
554.Op \&: Ns Ar format
555.Xc
556Perform a memory operation as indicated.  The
557.Ar memtype
558field specifies the memory type to operate on.
559The available memory types are device-dependent, the actual
560configuration can be viewed with the
561.Cm part
562command in terminal mode.
563Typically, a device's memory configuration at least contains
564the memory types
565.Ar flash
566and
567.Ar eeprom .
568All memory types currently known are:
569.Bl -tag -width "calibration" -compact
570.It calibration
571One or more bytes of RC oscillator calibration data.
572.It eeprom
573The EEPROM of the device.
574.It efuse
575The extended fuse byte.
576.It flash
577The flash ROM of the device.
578.It fuse
579The fuse byte in devices that have only a single fuse byte.
580.It hfuse
581The high fuse byte.
582.It lfuse
583The low fuse byte.
584.It lock
585The lock byte.
586.It signature
587The three device signature bytes (device ID).
588.It fuse Ns Em N
589The fuse bytes of ATxmega devices,
590.Em N
591is an integer number
592for each fuse supported by the device.
593.It application
594The application flash area of ATxmega devices.
595.It apptable
596The application table flash area of ATxmega devices.
597.It boot
598The boot flash area of ATxmega devices.
599.It prodsig
600The production signature (calibration) area of ATxmega devices.
601.It usersig
602The user signature area of ATxmega devices.
603.El
604.Pp
605The
606.Ar op
607field specifies what operation to perform:
608.Bl -tag -width noreset
609.It Ar r
610read device memory and write to the specified file
611.It Ar w
612read data from the specified file and write to the device memory
613.It Ar v
614read data from both the device and the specified file and perform a verify
615.El
616.Pp
617The
618.Ar filename
619field indicates the name of the file to read or write.
620The
621.Ar format
622field is optional and contains the format of the file to read or
623write.
624.Ar Format
625can be one of:
626.Bl -tag -width sss
627.It Ar i
628Intel Hex
629.It Ar s
630Motorola S-record
631.It Ar r
632raw binary; little-endian byte order, in the case of the flash ROM data
633.It Ar e
634ELF (Executable and Linkable Format)
635.It Ar m
636immediate; actual byte values specified on the command line, separated
637by commas or spaces.  This is good for programming fuse bytes without
638having to create a single-byte file or enter terminal mode.
639.It Ar a
640auto detect; valid for input only, and only if the input is not
641provided at
642.Em stdin .
643.It Ar d
644decimal; this and the following formats are only valid on output.
645They generate one line of output for the respective memory section,
646forming a comma-separated list of the values.
647This can be particularly useful for subsequent processing, like for
648fuse bit settings.
649.It Ar h
650hexadecimal; each value will get the string
651.Em 0x
652prepended.
653.It Ar o
654octal; each value will get a
655.Em 0
656prepended unless it is less than 8 in which case it gets no prefix.
657.It Ar b
658binary; each value will get the string
659.Em 0b
660prepended.
661.El
662.Pp
663The default is to use auto detection for input files, and raw binary
664format for output files.
665Note that if
666.Ar filename
667contains a colon, the
668.Ar format
669field is no longer optional since the filename part following the colon
670would otherwise be misinterpreted as
671.Ar format .
672.Pp
673When reading any kind of flash memory area (including the various sub-areas
674in Xmega devices), the resulting output file will be truncated to not contain
675trailing 0xFF bytes which indicate unprogrammed (erased) memory.
676Thus, if the entire memory is unprogrammed, this will result in an output
677file that has no contents at all.
678.Pp
679As an abbreviation, the form
680.Fl U Ar filename
681is equivalent to specifying
682.Fl U Em flash:w: Ns Ar filename Ns :a .
683This will only work if
684.Ar filename
685does not have a colon in it.
686.It Fl v
687Enable verbose output.
688More
689.Fl v
690options increase verbosity level.
691.It Fl V
692Disable automatic verify check when uploading data.
693.It Fl x Ar extended_param
694Pass
695.Ar extended_param
696to the chosen programmer implementation as an extended parameter.
697The interpretation of the extended parameter depends on the
698programmer itself.
699See below for a list of programmers accepting extended parameters.
700.El
701.Ss Terminal mode
702In this mode,
703.Nm
704only initializes communication with the MCU, and then awaits user
705commands on standard input.  Commands and parameters may be
706abbreviated to the shortest unambiguous form.  Terminal mode provides
707a command history using
708.Xr readline 3 ,
709so previously entered command lines can be recalled and edited.  The
710following commands are currently implemented:
711.Bl -tag -offset indent -width indent
712.It Ar dump memtype addr nbytes
713Read
714.Ar nbytes
715bytes from the specified memory area, and display them in the usual
716hexadecimal and ASCII form.
717.It Ar dump
718Continue dumping the memory contents for another
719.Ar nbytes
720where the previous
721.Ar dump
722command left off.
723.It Ar write memtype addr byte1 ... byteN
724Manually program the respective memory cells, starting at address
725.Ar addr ,
726using the values
727.Ar byte1
728through
729.Ar byteN .
730This feature is not implemented for bank-addressed memories such as
731the flash memory of ATMega devices.
732.It Ar erase
733Perform a chip erase.
734.It Ar send b1 b2 b3 b4
735Send raw instruction codes to the AVR device.  If you need access to a
736feature of an AVR part that is not directly supported by
737.Nm ,
738this command allows you to use it, even though
739.Nm
740does not implement the command. When using direct SPI mode, up to 3 bytes
741can be omitted.
742.It Ar sig
743Display the device signature bytes.
744.It Ar spi
745Enter direct SPI mode.  The
746.Em pgmled
747pin acts as slave select.
748.Em Only supported on parallel bitbang programmers.
749.It Ar part
750Display the current part settings and parameters.  Includes chip
751specific information including all memory types supported by the
752device, read/write timing, etc.
753.It Ar pgm
754Return to programming mode (from direct SPI mode).
755.It Ar vtarg voltage
756Set the target's supply voltage to
757.Ar voltage
758Volts.
759.Em Only supported on the STK500 and STK600 programmer.
760.It Ar varef Oo Ar channel Oc Ar voltage
761Set the adjustable voltage source to
762.Ar voltage
763Volts.
764This voltage is normally used to drive the target's
765.Em Aref
766input on the STK500.
767On the Atmel STK600, two reference voltages are available, which
768can be selected by the optional
769.Ar channel
770argument (either 0 or 1).
771.Em Only supported on the STK500 and STK600 programmer.
772.It Ar fosc freq Ns Op M Ns \&| Ns k
773Set the master oscillator to
774.Ar freq
775Hz.
776An optional trailing letter
777.Ar \&M
778multiplies by 1E6, a trailing letter
779.Ar \&k
780by 1E3.
781.Em Only supported on the STK500 and STK600 programmer.
782.It Ar fosc off
783Turn the master oscillator off.
784.Em Only supported on the STK500 and STK600 programmer.
785.It Ar sck period
786.Em STK500 and STK600 programmer only:
787Set the SCK clock period to
788.Ar period
789microseconds.
790.Pp
791.Em JTAG ICE only:
792Set the JTAG ICE bit clock period to
793.Ar period
794microseconds.
795Note that unlike STK500 settings, this setting will be reverted to
796its default value (approximately 1 microsecond) when the programming
797software signs off from the JTAG ICE.
798This parameter can also be used on the JTAG ICE mkII, JTAGICE3, and Atmel-ICE to specify the
799ISP clock period when operating the ICE in ISP mode.
800.It Ar parms
801.Em STK500 and STK600 programmer only:
802Display the current voltage and master oscillator parameters.
803.Pp
804.Em JTAG ICE only:
805Display the current target supply voltage and JTAG bit clock rate/period.
806.It Ar verbose Op Ar level
807Change (when
808.Ar level
809is provided), or display the verbosity level.
810The initial verbosity level is controlled by the number of
811.Fl v
812options given on the commandline.
813.It Ar \&?
814.It Ar help
815Give a short on-line summary of the available commands.
816.It Ar quit
817Leave terminal mode and thus
818.Nm avrdude .
819.El
820.Ss Default Parallel port pin connections
821(these can be changed, see the
822.Fl c
823option)
824.TS
825ll.
826\fBPin number\fP        \fBFunction\fP
8272-5     Vcc (optional power supply to MCU)
8287       /RESET (to MCU)
8298       SCK (to MCU)
8309       MOSI (to MCU)
83110      MISO (from MCU)
83218-25   GND
833.TE
834.Ss debugWire limitations
835The debugWire protocol is Atmel's proprietary one-wire (plus ground)
836protocol to allow an in-circuit emulation of the smaller AVR devices,
837using the
838.Ql /RESET
839line.
840DebugWire mode is initiated by activating the
841.Ql DWEN
842fuse, and then power-cycling the target.
843While this mode is mainly intended for debugging/emulation, it
844also offers limited programming capabilities.
845Effectively, the only memory areas that can be read or programmed
846in this mode are flash ROM and EEPROM.
847It is also possible to read out the signature.
848All other memory areas cannot be accessed.
849There is no
850.Em chip erase
851functionality in debugWire mode; instead, while reprogramming the
852flash ROM, each flash ROM page is erased right before updating it.
853This is done transparently by the JTAG ICE mkII (or AVR Dragon).
854The only way back from debugWire mode is to initiate a special
855sequence of commands to the JTAG ICE mkII (or AVR Dragon), so the
856debugWire mode will be temporarily disabled, and the target can
857be accessed using normal ISP programming.
858This sequence is automatically initiated by using the JTAG ICE mkII
859or AVR Dragon in ISP mode, when they detect that ISP mode cannot be
860entered.
861.Ss FLIP version 1 idiosyncrasies
862Bootloaders using the FLIP protocol version 1 experience some very
863specific behaviour.
864.Pp
865These bootloaders have no option to access memory areas other than
866Flash and EEPROM.
867.Pp
868When the bootloader is started, it enters a
869.Em security mode
870where the only acceptable access is to query the device configuration
871parameters (which are used for the signature on AVR devices).
872The only way to leave this mode is a
873.Em chip erase .
874As a chip erase is normally implied by the
875.Fl U
876option when reprogramming the flash, this peculiarity might not be
877very obvious immediately.
878.Pp
879Sometimes, a bootloader with security mode already disabled seems to
880no longer respond with sensible configuration data, but only 0xFF for
881all queries.
882As these queries are used to obtain the equivalent of a signature,
883.Nm
884can only continue in that situation by forcing the signature check
885to be overridden with the
886.Fl F
887option.
888.Pp
889A
890.Em chip erase
891might leave the EEPROM unerased, at least on some
892versions of the bootloader.
893.Ss Programmers accepting extended parameters
894.Bl -tag -offset indent -width indent
895.It Ar JTAG ICE mkII
896.It Ar JTAGICE3
897.It Ar Atmel-ICE
898.It Ar AVR Dragon
899When using the JTAG ICE mkII, JTAGICE3, Atmel-ICE or AVR Dragon in JTAG mode, the
900following extended parameter is accepted:
901.Bl -tag -offset indent -width indent
902.It Ar jtagchain=UB,UA,BB,BA
903Setup the JTAG scan chain for
904.Ar UB
905units before,
906.Ar UA
907units after,
908.Ar BB
909bits before, and
910.Ar BA
911bits after the target AVR, respectively.
912Each AVR unit within the chain shifts by 4 bits.
913Other JTAG units might require a different bit shift count.
914.El
915.It Ar AVR910
916.Bl -tag -offset indent -width indent
917.It Ar devcode=VALUE
918Override the device code selection by using
919.Ar VALUE
920as the device code.
921The programmer is not queried for the list of supported
922device codes, and the specified
923.Ar VALUE
924is not verified but used directly within the
925.Ql T
926command sent to the programmer.
927.Ar VALUE
928can be specified using the conventional number notation of the
929C programming language.
930.El
931.Bl -tag -offset indent -width indent
932.It Ar no_blockmode
933Disables the default checking for block transfer capability.
934Use
935.Ar no_blockmode
936only if your
937.Ar AVR910
938programmer creates errors during initial sequence.
939.El
940.It Ar buspirate
941.Bl -tag -offset indent -width indent
942.It Ar reset={cs,aux,aux2}
943The default setup assumes the BusPirate's CS output pin connected to
944the RESET pin on AVR side. It is however possible to have multiple AVRs
945connected to the same BP with MISO, MOSI and SCK lines common for all of them.
946In such a case one AVR should have its RESET connected to BusPirate's
947.Pa CS
948pin, second AVR's RESET connected to BusPirate's
949.Pa AUX
950pin and if your BusPirate has an
951.Pa AUX2
952pin (only available on BusPirate version v1a with firmware 3.0 or newer)
953use that to activate RESET on the third AVR.
954.Pp
955It may be a good idea to decouple the BusPirate and the AVR's SPI buses from
956each other using a 3-state bus buffer. For example 74HC125 or 74HC244 are some
957good candidates with the latches driven by the appropriate reset pin (cs,
958aux or aux2). Otherwise the SPI traffic in one active circuit may interfere
959with programming the AVR in the other design.
960.It Ar spifreq=<0..7>
961The SPI speed for the Bus Pirate's binary SPI mode:
962.Bd -literal
9630 ..  30 kHz   (default)
9641 .. 125 kHz
9652 .. 250 kHz
9663 ..   1 MHz
9674 ..   2 MHz
9685 ..   2.6 MHz
9696 ..   4 MHz
9707 ..   8 MHz
971.Ed
972.It Ar rawfreq=<0..3>
973Sets the SPI speed and uses the Bus Pirate's binary "raw-wire" mode:
974.Bd -literal
9750 ..   5 kHz
9761 ..  50 kHz
9772 .. 100 kHz   (Firmware v4.2+ only)
9783 .. 400 kHz   (v4.2+)
979.Ed
980.Pp
981The only advantage of the "raw-wire" mode is the different SPI frequencies
982available. Paged writing is not implemented in this mode.
983.It Ar ascii
984Attempt to use ASCII mode even when the firmware supports BinMode (binary
985mode).
986BinMode is supported in firmware 2.7 and newer, older FW's either don't
987have BinMode or their BinMode is buggy. ASCII mode is slower and makes
988the above
989.Ar reset= , spifreq=
990and
991.Ar rawfreq=
992parameters unavailable. Be aware that ASCII mode is not guaranteed to work
993with newer firmware versions, and is retained only to maintain compatibility
994with older firmware versions.
995.It Ar nopagedwrite
996Firmware versions 5.10 and newer support a binary mode SPI command that enables
997whole pages to be written to AVR flash memory at once, resulting in a
998significant write speed increase. If use of this mode is not desirable for some
999reason, this option disables it.
1000.It Ar nopagedread
1001Newer firmware versions support in binary mode SPI command some AVR Extended
1002Commands. Using the "Bulk Memory Read from Flash" results in a
1003significant read speed increase. If use of this mode is not desirable for some
1004reason, this option disables it.
1005.It Ar cpufreq=<125..4000>
1006This sets the AUX pin to output a frequency of
1007.Ar n
1008kHz. Connecting
1009the AUX pin to the XTAL1 pin of your MCU, you can provide it a clock,
1010for example when it needs an external clock because of wrong fuses settings.
1011Make sure the CPU frequency is at least four times the SPI frequency. 
1012.It Ar serial_recv_timeout=<1...>
1013This sets the serial receive timeout to the given value.
1014The timeout happens every time avrdude waits for the BusPirate prompt.
1015Especially in ascii mode this happens very often, so setting a smaller value
1016can speed up programming a lot.
1017The default value is 100ms. Using 10ms might work in most cases.
1018.El
1019.It Ar Wiring
1020When using the Wiring programmer type, the
1021following optional extended parameter is accepted:
1022.Bl -tag -offset indent -width indent
1023.It Ar snooze=<0..32767>
1024After performing the port open phase, AVRDUDE will wait/snooze for
1025.Ar snooze
1026milliseconds before continuing to the protocol sync phase.
1027No toggling of DTR/RTS is performed if
1028.Ar snooze
1029is greater than 0.
1030.El
1031.It Ar PICkit2
1032Connection to the PICkit2 programmer:
1033.Bd -literal
1034(AVR)    (PICkit2)
1035RST  -   VPP/MCLR (1)
1036VDD  -   VDD Target (2) -- possibly optional if AVR self powered
1037GND  -   GND (3)
1038MISO -   PGD (4)
1039SCLK -   PDC (5)
1040MOSI -   AUX (6)
1041
1042.Ed
1043Extended commandline parameters:
1044.Bl -tag -offset indent -width indent
1045.It Ar clockrate=<rate>
1046Sets the SPI clocking rate in Hz (default is 100kHz). Alternately the -B or -i options can be used to set the period.
1047.It Ar timeout=<usb-transaction-timeout>
1048Sets the timeout for USB reads and writes in milliseconds (default is 1500 ms).
1049.El
1050.El
1051.Sh FILES
1052.Bl -tag -offset indent -width /dev/ppi0XXX
1053.It Pa /dev/ppi0
1054default device to be used for communication with the programming
1055hardware
1056.It Pa ${PREFIX}/etc/avrdude.conf
1057programmer and parts configuration file
1058.It Pa ${HOME}/.avrduderc
1059programmer and parts configuration file (per-user overrides)
1060.It Pa ~/.inputrc
1061Initialization file for the
1062.Xr readline 3
1063library
1064.It Pa ${PREFIX}/share/doc/avrdude/avrdude.pdf
1065Schematic of programming hardware
1066.El
1067.\" .Sh EXAMPLES
1068.Sh DIAGNOSTICS
1069.Bd -literal
1070avrdude: jtagmkII_setparm(): bad response to set parameter command: RSP_FAILED
1071avrdude: jtagmkII_getsync(): ISP activation failed, trying debugWire
1072avrdude: Target prepared for ISP, signed off.
1073avrdude: Please restart avrdude without power-cycling the target.
1074.Ed
1075.Pp
1076If the target AVR has been set up for debugWire mode (i. e. the
1077.Em DWEN
1078fuse is programmed), normal ISP connection attempts will fail as
1079the
1080.Em /RESET
1081pin is not available.
1082When using the JTAG ICE mkII in ISP mode, the message shown indicates
1083that
1084.Nm
1085has guessed this condition, and tried to initiate a debugWire reset
1086to the target.
1087When successful, this will leave the target AVR in a state where it
1088can respond to normal ISP communication again (until the next power
1089cycle).
1090Typically, the same command is going to be retried again immediately
1091afterwards, and will then succeed connecting to the target using
1092normal ISP communication.
1093.Sh SEE ALSO
1094.Xr avr-objcopy 1 ,
1095.Xr ppi 4 ,
1096.Xr libelf 3,
1097.Xr readline 3
1098.Pp
1099The AVR microcontroller product description can be found at
1100.Pp
1101.Dl "http://www.atmel.com/products/AVR/"
1102.\" .Sh HISTORY
1103.Sh AUTHORS
1104.Nm Avrdude
1105was written by Brian S. Dean <bsd@bsdhome.com>.
1106.Pp
1107This man page by
1108.ie t J\(:org Wunsch.
1109.el Joerg Wunsch.
1110.Sh BUGS
1111Please report bugs via
1112.Dl "http://savannah.nongnu.org/bugs/?group=avrdude" .
1113.Pp
1114The JTAG ICE programmers currently cannot write to the flash ROM
1115one byte at a time.
1116For that reason, updating the flash ROM from terminal mode does not
1117work.
1118.Pp
1119Page-mode programming the EEPROM through JTAG (i.e. through an
1120.Fl U
1121option) requires a prior chip erase.
1122This is an inherent feature of the way JTAG EEPROM programming works.
1123This also applies to the STK500 and STK600 in parallel programming mode.
1124.Pp
1125The USBasp and USBtinyISP drivers do not offer any option to distinguish multiple
1126devices connected simultaneously, so effectively only a single device
1127is supported.
1128.Pp
1129The avrftdi driver allows one to select specific devices using any combination of vid,pid
1130serial number (usbsn) vendor description (usbvendoror part description (usbproduct)
1131as seen with lsusb or whatever tool used to view USB device information. Multiple
1132devices can be on the bus at the same time. For the H parts, which have multiple MPSSE
1133interfaces, the interface can also be selected.  It defaults to interface 'A'.
Note: See TracBrowser for help on using the repository browser.