3.1 Terminal Mode Commands

In this mode, AVRDUDE 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 readline(3), so previously entered command lines can be recalled and edited.

The addr and len parameters of the dump, read, disasm, write, save and erase commands can be negative with the same syntax as substring computations in perl or python. The table below details their meaning with respect to an example memory of size sz=0x800 (2048 bytes).

The following commands are implemented for all programmers:

dump memory addr len

Read from the specified memory interval (see above), and display in the usual hexadecimal and ASCII form.

dump memory addr

Read from memory addr as many bytes as the most recent dump memory addr len command with this very memory had specified (default 256 bytes), and display them.

dump memory

Continue dumping from the memory and location where the most recent dump command left off; if no previous dump command has addressed a memory an error message will be shown.

dump

Continue dumping from the memory and location where the most recent dump command left off; if no previous dump command has addressed a memory an error message will be shown.

dump memory addr …

Start reading from addr, all the way to the last memory address (deprecated: use dump memory addr -1).

dump memory …

Read all bytes from the specified memory, and display them (deprecated: use dump memory 0 -1).

read

Can be used as an alias for dump.

disasm [options] dump-arguments

Like dump, the disasm command displays a part of the specified memory, albeit by interpreting the memory contents as AVR opcodes and showing it as assembler source code. Unlike dump, the disasm command has options; these control how disasm displays its result (see below). Other than that, the syntax of specifying the memory and its to be processed interval is virtually the same as that of dump: the default disasm length is 32 bytes, though, and sometimes the length can be slightly shorter or longer than requested, so that the memory section for disasm aligns with opcodes. Disasm options, once set, stay in force until switched off, typically by changing the case of the option. This way, a simple disasm without further options can be used to step through memory keeping the appearance. Disasm knows the following options:

-g

Generate avr-gcc source: this sets -sOFQ and outputs a .text preamble and a main symbol unless the disassembly emits one itself; -G (default) switches off -g and stops outputting a preamble

-A

Do not show addresses; -a (the default) shows addresses

-O

Do not show opcode bytes; -o (the default) show opcode bytes

-C

Do not show comments; -c (the default) show comments

-f

Show affected flags in SREG, eg, ---SVNZC for the sbiw opcode; -F (the default) do not show SREG flags

-q

Show the number of machine cycles that an opcode takes; -Q (the default) do not show the cycles

-n

Put the opcode full name into comment (eg, subtract immediate from word); -N (the default) do not show the full opcode names

-e

Put a technical explanation of the opcode into the comment, eg, Rd+1:Rd <-- Rd+1:Rd - K for the sbiw opcode; -E (the default) do not show technical explanations

-S

Use AVR instruction set style: this means that register pairs are shown as, eg, in r31:30 instead of r30; -s (the default) use avr-gcc code style

-L

Do not preprocess labels; -l (the default) preprocess jump/call labels

-d

Decode all opcodes including those that are undocumented; -D (the default) decode only opcodes that are valid for the part

-z

Zap the list of jumps and calls before disassembly

-t=file

Delete symbols from a previously read tagfile, if any, and read the tagfile file for assigning addresses to symbol names.

The tagfile is an ASCII file where each line describes a symbol for code label addresses (L), variable addresses in flash (P) and variables addresses in memory or I/O space (M). Hashmarks start a tagfile comment that extends to the end of the line and is ignored by disasm. Here is a defining example of how a tagfile looks like

0x7f54 L putch Outputs a char # L are code labels 0x7ffe P W 1 version16 A word integer # P are PGM data 0x7f80 P A 4 headings Column headers # Auto-aligned strings 0x0100 M B 2048 sram 2 kB SRAM # Memory address

Code labels L can be, eg, function names in program space or goto labels. They use up to four columns separated by white space: the address, the letter L, the symbolic name of the label and an optional comment column for the symbol, which is copied by disasm into the disassembly comment column, should this label be referenced or used by the code. Variable symbols have a P or M in the second column; they can be bytes or words as determined by the letter B or W in the third column and either single variables or arrays as specified by the multiplicity count in the forth column. P symbols, but not M symbols, can also be the base location of nul-terminated strings as encoded by A or S in the third column. Out of necessity, the space occupied by A/S strings varies. The difference between A and S symbols is that the array of A strings might have an additional nul character to auto-align the space occupied by them to an even address. The fifth column is the symbolic name for the P or M address that can be used by disasm to output relevant addresses symbolically. P areas described in the tagfile also tell disasm that the corresponding area is not code and should not be disassembled as such; instead the directives are used for disassembly of that area. As with L labels, P and M variables may have an optional final comment column pertaining to the symbol that may be output in the disassembly column as and when the corresponding variables are used.

Tagfiles are useful for disassembly to make the output of disasm more readable. They can be built manually and incrementally as one’s under‐ standing of the code grows. Alternatively, the bash shell script elf2tag can automatically generate a tag file from the .elf file that produced the flash contents:

$ elf2tag application.elf >application.tag

elf2tag uses the avr-objdump -d disassembly to create L labels and avr-nm to generate M symbols.

write memory addr data[,] {data[,]}

Manually program the respective memory cells, starting at address addr, using the data items provided. The terminal implements reading from and writing to flash, EEPROM, bootrow and usersig 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, depending on the programmer, might also have flash and EEPROM directly accessed without cache.

Items data can have the following formats:

Type	Example	Size (bytes)
String	"Hello, world\n"	varying
File	C:/My\ projects/blink.hex	varying
File with format	blink.hex:i	varying
Character	'A'	1
Binary integer	0b101010	1, 2, 4, or 8
Octal integer	012345	1, 2, 4, or 8
Decimal integer	12345	1, 2, 4, or 8
Hexadecimal integer	0x12345	1, 2, 4, or 8
Decimal float	3.1415926	4
Hexadecimal float	0xA.8p2	4
Decimal double	3.141592653589793D	8
Hexadecimal double	0xA.8p2D	8

data can be binary, octal, decimal or hexadecimal integers, floating point numbers or C-style strings and characters. If nothing matches, data will be interpreted as a name of a file containing data, which will be read and inserted at this point. In order to force the interpretation of a data item as file, e.g., when the file name would be understood as a number otherwise, the file name can be given a :f format specifier. In absence of a format suffix, the terminal will try to auto-detect the file format.

For integers, an optional case-insensitive suffix specifies the data size as in the table below:

LL

8 bytes / 64 bits

L

4 bytes / 32 bits

H or S

2 bytes / 16 bits

HH

1 byte / 8 bits

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.

An optional U suffix makes integers unsigned. Ordinary 0x hexadecimal and 0b binary integers are always treated as unsigned. +0x, -0x, +0b and -0b numbers with an explicit sign 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.

Ordinary 0x hexadecimal and 0b binary 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 hexadecimal/binary 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.

One trailing comma at the end of data items is ignored to facilitate copy and paste of lists.

write memory addr data

The start address addr may be omitted if the size of the memory being written to is one byte.

write memory addr len data[,] {data[,]} …

The ellipsis … form writes the data to the entire memory intervall addressed by addr len and, if necessary, pads the remaining space by repeating the last data item. The fill write command does not write beyond the specified memory area even if more data than needed were given.

save memory {addr len} file[:format]

Save one or more memory segments to a file in a format specified by the :format letter. The default is :r for raw binary. Each memory segment is described by an address and length pair. In absence of any memory segments the entire memory is saved to the file. Only Motorola S-Record (:s) and Intel Hex (:i or :I) formats store address information with the saved data. Avrdude cannot currently save ELF file formats. All the other file formats lose the address information and concatenate the chosen memory segments into the output file. If the file name is - then avrdude writes to stdout.

backup memlist file[:format]

Backup one or more memories to the specified file using the selected format. The default format for a single-memory backup is :r (raw binary); for multi-memory backups it is :I (Intel Hex with comments). Memlist can be a comma separated list of memories just as in the -U command line argument. backup flushes the cache before reading memories.

restore memlist file[:format]

Restore one or more memories from the specified file. It is the user’s responsibility to erase memories as needed beforehand: some paged memories look like NOR-memory when using certain programmers, meaning programming cannot set bits to 1 (eg, flash under most programmers). These memories need to be erased beforehand using the erase command (see below). The format only needs to be specified if it cannot be automatically detected, eg, when the file is - for standard input. Memlist can be a comma separated list of memories just as in the -U command line argument. restore flushes the cache before writing memories and resets the cache after writing memories. Note that restoring read-only memories verifies file contents with the corresponding microprocessor’s memories.

verify memlist file[:format]

Compare one or more memories with the specified file. Memlist can be a comma separated list of memories just as in the -U command line argument. verify flushes the cache before verifying memories.

erase

Perform a chip erase and discard all pending writes to flash, EEPROM and bootrow. Note that EEPROM will be preserved if the EESAVE fuse bit is active, ie, had a corresponding value at the last reset prior to the operation.

erase memory

Erase the entire specified memory.

erase memory addr len

Erase a section of the specified memory.

flush

Synchronise with the device all pending writes to flash, EEPROM, bootrow and usersig. With some programmer and part combinations, flash (and sometimes EEPROM, too) looks like a NOR memory, i.e., a write can only clear bits, never set them. For NOR memories a page erase or, if not available, a chip erase needs to be issued before writing arbitrary data. Usersig is unaffected by a chip erase. When a memory looks like a NOR memory, 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 routine should be called sparingly.

abort

Normally, caches are only ever actually written to the device when using flush, at the end of the terminal session after typing quit, or after EOF on input is encountered. The abort command resets the cache discarding all previous writes to the flash, EEPROM, bootrow and usersig cache.

config [opts]

Show all configuration properties of the part; these are usually bitfields in fuses or lock bits bytes that can take on values, which typically have a mnemonic name. Each part has their own set of configurable items. The option -f groups the configuration properties by the fuses and lock bits byte they are housed in, and shows the current value of these memories as well. Config -a outputs an initialisation script with all properties and all possible respective assignments. The currently assigned mnemonic values are the ones that are not commented out. The option -v increases the verbosity of the output of the config command.

config [opts] property [opts]

Show the current value of the named configuration property. Wildcards or initial strings are permitted (but not both), in which case the current values of all matching properties are displayed.

config [opts] property= [opts]

Show all possible values of the named configuration property (notice the trailing =). The one that is currently set is the only one not commented out. As before, wildcards or initial strings are permitted.

config [opts] property=value [opts]

Modify the named configuration property to the given value. The corresponding fuse or lock bits will be changed immediately but the change will normally only take effect the next time the part is reset, at which point the fuses and lock bits are utilised. Value can either be a valid integer or one of the symbolic mnemonics, if known. Wildcards or initial strings are permitted for either the property or the assigned mnemonic value, but an assignment only happens if both the property and the name can be uniquely resolved.

It is quite possible, as is with direct writing to the underlying fuses and lock bits, to brick a part, i.e., make it unresponsive to further programming with the chosen programmer: here be dragons.

factory reset

Resets the connected part to factory state as far as possible (bootloaders, for example, cannot write fuses and may not have a means to erase EEPROM). This command may change the clock frequency F_CPU of the part after the next MCU reset when the changed fuse values come into effect. As such, this may require that future avrdude calls use a different bit clock rate up to F_CPU/4 for the programmer next time. Note that the command factory can be abbreviated but the required argument reset needs to be spelled out in full.

regfile [opts]

regfile with no further argument displays the register file of a part, i.e., all register names and their contents in io memory, if possible: note that external programming cannot read the registers of classic parts (ISP or TPI interfaces).

Option -a displays the register I/O addresses in addition; -m displays the register memory addresses used for lds/sts opcodes instead of the I/O addresses. Option -s also shows the size of the register in bytes whilst -v shows a slightly expanded register explanation alongside each register.

regfile [opts] reg [opts]

regfile together with a register name reg shows all those registers that are matched by reg. Wildcards or partial strings are permitted but not both. Register names have the form module.name or module.instance.name. If the provided reg is a full, existing register name, e.g., porta.out then that is the only register that is displayed even though that might be a partial name of another register, eg, porta.outdir. If the provided reg is the same as instance.name or name then partial matching is no longer utilised and all module registers with that exact instance.name or name are shown. Partial matching can be forced through use of wildcards, e.g., using porta.out*

regfile [opts] reg=value [opts]

This sets a single register addressed by reg to the given value. Only external programming of modern parts (those with UPDI interface) can read from and write to register io memory, but as that memory is volatile, the contents will be lost after reset.

include [opts] file

Include contents of the named file file as if it was typed. This is useful for batch scripts, e.g., recurring initialisation code for fuses. The include option -e prints the lines of the file as comments before processing them; on a non-zero verbosity level the line numbers are printed, too.

signature

Display the device signature bytes.

part [opts]

Display the current part information, including supported programming modes, memory and variants tables. Use -m to only print the memory table, and -v to only print the variants table.

verbose ]level]

Change (when level is provided), or display the verbosity level. The initial verbosity level is controlled by the number of -v options given on the command line.

quell [level]

Change (when level is provided), or display the quell level. 1 is used to suppress progress reports. 2 or higher yields progressively quieter operations. The initial quell level is controlled by the number of -q options given on the command line.

?

help

Give a short on-line summary of the available commands.

quit

Leave terminal mode and thus AVRDUDE.

q

Can be used as an alias for quit.

!line

Run the shell line in a subshell, e.g., !ls *.hex. Subshell commands take the rest of the line as their command. For security reasons, they must be enabled explictly by putting allow_subshells = yes; into your ${HOME}/.config/avrdude/avrdude.rc or ${HOME}/.avrduderc file.

# comment

Place comments onto the terminal line (useful for scripts).

In addition, the following commands are supported on some programmers:

pgerase memory addr

Erase one page of the memory specified.

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 AVRDUDE, this command allows you to use it, even though AVRDUDE does not implement the command. When using direct SPI mode, up to 3 bytes can be omitted.

spi

Enter direct SPI mode. The pgmled pin acts as chip select. Only supported on parallel bitbang programmers, and partially by USBtiny. Chip Select must be externally held low for direct SPI when using USBtinyISP, and send must be a multiple of four bytes.

pgm

Return to programming mode (from direct SPI mode).

vtarg voltage

Set the target’s supply voltage to voltage Volts.

varef [channel] voltage

Set the adjustable voltage source to voltage Volts. This voltage is normally used to drive the target’s Aref input on the STK500 and STK600. The STK600 offers two reference voltages, which can be selected by the optional parameter channel (either 0 or 1).

fosc freq[M|k]

Set the programming oscillator to freq Hz. An optional trailing letter M multiplies by 1E6, a trailing letter k by 1E3.

fosc off

Turn the programming oscillator off.

sck period

Set the SCK clock period to period microseconds. Note that some official Microchip programmers store the bitclock setting and will continue to use it until a diferent value is provided. See -B bitclock for more information.

parms

Display programmer specific parameters.

This document was generated by Stefan Rueger on August 24, 2024 using texi2html 1.82.