plucky (3) using_tools.3avr.gz
NAME
using_tools - Using the GNU tools
This is a short summary of the AVR-specific aspects of using the GNU tools. Normally, the generic
documentation of these tools is fairly large and maintained in texinfo files. Command-line options are
explained in detail in the manual page.
Options for the C compiler avr-gcc
Machine-specific options for the AVR
The following machine-specific options are recognized by the C compiler frontend. The preprocessor will
define the macros __AVR and __AVR__ (to the value 1) when compiling for an AVR target. The macro AVR will
be defined as well, except in strict ANSI mode.
There are many options supported by avr-gcc, which also depend on the compiler version. For a complete
overview, please see the documentation of avr-gcc's command line options. Here are links to supported
options of the respective release series:
• Current development (work in progress)
• v14
• v13.2, v13.3
• v12.3, v12.4
• v11
• v10
• v9
• v8
• v7
• v6
• v5
• v4.9
• v4.8
• v4.7
Apart from the documentation of command line options, the linked pages also contain:
• The documentation of built-in macros like __AVR_ARCH__, __AVR_ATmega328P__ and __AVR_HAVE_MUL__, just
to mention a few.
• How the compiler treats the RAMPX, RAMPY, RAMPZ and RAMPD special function registers on devices that
have (one of) them.
• How the compiler treats the EIND special function register on devices with more than 128 KiB of program
memory, and how indirect calls are realized on such devices.
-mmcu=arch
-mmcu=mcu
Compile code for architecture arch resp. AVR device mcu.
Since GCC v5, the compiler no more supports indivitual devices, instead the compiler comes with device
specs files that describe which options to use with each sub-processes like pre-processor, compiler
proper, assembler and linker.
The purpose of these specs files is to add support for AVR devices that the compiler does not yet
support.
The easiest way to add support for an unsupported device is to use device support from an atpack archive
as provided by the hardware manufacturer. Apart from the mcu specific specs file, it provides device
headers io*.h, startup code crtmcu.o and device library libmcu.a.
Selected general compiler options
The following general gcc options might be of some interest to AVR users.
-On
Optimization level n. Increasing n is meant to optimize more.
-O0 reduces compilation time and makes debugging produce the expected results. This is the default.
Turning off all optimizations will prevent some warnings from being issued since the generation of those
warnings depends on code analysis steps that are only performed when optimizing (unreachable code, unused
variables). Moreover, the delay routines in <util/delay.h> require optimization to be turned on.
-O2 optimizes for speed, but without enabling very expensive optimizations like -O3 does.
-Os turns on all -O2 optimizations except those that often increase code size. In most cases, this is the
preferred optimization level for AVR programs.
-Og optimizes debugging experience. This should be the optimization level of choice for the standard
edit-compile-debug cycle, offering a reasonable level of optimization while maintaining fast compilation
and a good debugging experience.
-O3 attempts to inline all 'simple' functions and might unroll some loops. For the AVR target, this will
normally constitute a large pessimization due to the code increasement.
-O is equivalent to -O1. The compiler tries to reduce code size and execution time, without performing
any optimizations that take a great deal of compilation time.
See also the appropriate FAQ entry for issues regarding debugging optimized code.
-Wp,preprocessor-options
-Wa,assembler-options
-Wl,linker-options
Pass the listed options to the C preprocessor, the assembler or the linker, respectively. Several
options can be passed at once when they are separated by a , (comma).
-g Generate debugging information that can be used by avr-gdb. GCC v12 changed the default from STABS to
DWARF. Different DWARF levels can be selected by -g2 or -gdwarf-3.
The compiler may use GNU extensions to the DWARF format. When a debugger has problems with that, try
-gstrict-dwarf.
-x lang
-x none
Compile the following files in language lang. Values for lang are: c, c++, assembler, assembler-with-
cpp and none.
For example, GCC does not recognize the .asm file extension as assembly source. With -x assembler-with-
cpp file.asm, the compiler first runs the C preprocessor on file.asm (so that #include <avr/io.h> can be
used in assembly), and then calls the assembler.
Another use case is to compile a C file that's read from standard input, which is specified as - (dash)
instead of the name of a source file. As no source file name is specified, the compiler must be told
which language to use: The command
$ echo '#include <avr/io.h>' | avr-gcc -xc - -mmcu=atmega8 -E -dM | grep _VECTOR
pre-processes the C file #include <avr/io.h> and writes all macro definitions to stdout. The output is
then filtered by grep to show all possible ISR vector names for ATmega8.
-x none returns to the default for the following inputs, i.e. infer the respective source languages from
the file extensions.
-save-temps
-save-temps=obj
-save-temps=cwd
-fverbose-asm
-dumpbase base
-dumpdir dir
Don't remove temporary, intermediate files like C preprocessor output and assembly code generated by
the compiler. The intermediate files have file extension .i (preprocessed C), .ii (preprocessed C++)
and .s (preprocessed assembly, compiler-generated assembly).
-dumpbase and -dumpdir can be used to adjust file names and locations.
With -fverbose-asm, the compiler adds the high level source code to the assembly output. Compiling
without debugging information (-g0) improves legibility of the generated assembly.
The preprocessed files can be used to check if macro expansions work as expected. With -g3 or higher, the
preprocessed files will also contain all macro definitions and indications where they are defined: Built-
in, on the command line, or in some header file as indicated by #line notes.
-lname
Locate the archive library named libname.a, and use it to resolve currently unresolved symbols from
it. The library is searched along a path that consists of builtin pathname entries that have been
specified at configure time (e. g. /usr/local/avr/lib on Unix systems), possibly extended by pathname
entries as specified by -L options (that must precede the -l options on the command-line).
-Lpath
Additional directory path to look for archive libraries requested by -l options.
-ffunction-sections
-fdata-sections
Put each function resp. object in static storage in its own input section. This is used with
-Wl,--gc-sections so the linker can better garbage-collect unused sections, which are sections that
are neither referenced by other sections, nor are marked as KEEP, nor are referenced by an entry
symbol.
-mrelax
Replace JMP and CALL instructions with the faster and shorter RJMP and RCALL instructions if
possible. That optimization is performed by the linker, and the assembler must not resolve some
expressions, which is all arranged by -mrelax.
-Tbss org
-Tdata org
-Ttext org
Start the .bss, .data, or .text section at VMA address org, respectively.
-T scriptfile
Use scriptfile as the linker script, replacing or augmenting the default linker script.
Default linker scripts are stored in a system-specific location (e. g. under /usr/local/avr/lib/ldscripts
on Unix systems), and consist of the AVR architecture name (avr2 through avrxmega7) with the suffix .x
appended. They describe how the various memory sections will be linked together and which input sections
go into them. Notice that the default linker scripts are part of the linker binary, changing them on file
will have no effect.
For a simple linker script augmentation, see the avr-gcc Wiki on named address spaces.
-nostdlib
Don't link against standard libraries.
-nodefaultlibs
Don't link against default libraries.
-nodevicelib
Don't link against AVR-LibC's libmcu.a that contains EEPROM support and other stuff. This can be used
when no such library is available.
-nostartfiles
Don't link against AVR-LibC's startup code crtmcu.o.
Notice that parts of the startup code are provided by libgcc.a. To get rid of that, one can -nostdlib or
-nodefaultlibs; however that also removes other code like functions required for arithmetic. To just get
rid of the startup bits, define the respective symbols, for example
-Wl,--defsym,__do_clear_bss=0 and similar for __do_copy_data, __do_global_ctors and __do_global_dtors.
-funsigned-char
This option changes the binary interface!
Make any unqualfied char type an unsigned char. Without this option, they default to a signed char.
-funsigned-bitfields
This option changes the binary interface!
Make any unqualified bitfield type unsigned. By default, they are signed.
-fshort-enums
This option changes the binary interface!
Allocate to an enum type only as many bytes as it needs for the declared range of possible values.
Specifically, the enum type will be equivalent to the smallest integer type which has enough room.
-fpack-struct
This option changes the binary interface!
Pack all structure members together without holes.
-fno-jump-tables
Do not generate tablejump instructions. By default, jump tables can be used to optimize switch
statements. When turned off, sequences of compare statements are used instead. Jump tables are
usually faster to execute on average, but in particular for switch statements, where most of the
jumps would go to the default label, they might waste a bit of flash memory.
Note: Sinve GCC v4.9.2, tablejump code uses the ELPM instruction to read from jump tables. In older
version, use the -fno-jump-tables switch when compiling a bootloader for devices with more than 64 KiB of
code memory.
-ffreestanding
Assume a 'freestanding' environment as per the C standard. This turns off automatic builtin functions
(though they can still be reached by prepending __builtin_ to the actual function name). It also
makes the compiler not complain when main() is declared with a void return type. (In most cases,
main() won't even return anyway, and hence using a return type of int has no downsides at all).
However, this option also turns off all optimizations normally done by the compiler which assume that
functions known by a certain name behave as described by the standard. For example, applying the function
strlen() to a literal string will normally cause the compiler to immediately replace that call by the
actual length of the string, while with -ffreestanding, it will always call strlen() at run-time.
Options for the assembler avr-as
Note
The preferred way to assemble a file is by means of using avr-gcc:
• avr-gcc, which is a driver program to call sub-programs like the compiler proper or the assembler,
knows which options it has to add to the assembler's command line, like: -mmcu=arch, -mno-skip-bug,
etc.
• avr-gcc will call the C preprocessor on the assembler input for sources with extensions .S and .sx.
For other extensions, use
$ avr-gcc -x assembler-with-cpp file.asm ...
This allows to use C preprocessor directives like
#include <avr/io.h>
in assembly sources.
Machine-specific assembler options
-mmcu=architecture
-mmcu=mcu
avr-as does not support all mcus supported by the compiler. As explained in the note above, the
preferred way to run the assembler is by using the compiler driver avr-gcc.
-mall-opcodes
Turns off opcode checking, and allows any possible AVR opcode to be assembled.
-mno-skip-bug
Don't emit a warning when trying to skip a 2-word instruction with a CPSE/SBIC/SBIS/SBRC/SBRS
instruction. Early AVR devices suffered from a hardware bug where these instructions could not be
properly skipped.
-mno-wrap
For RJMP/RCALL instructions, don't allow the target address to wrap around for devices that have more
than 8 KiB of memory.
--gstabs
Generate .stabs debugging symbols for assembler source lines. This enables avr-gdb to trace through
assembler source files. This option must not be used when assembling sources that have been generated
by the C compiler; these files already contain the appropriate line number information from the C
source files.
-a[cdhlmns=file]
Turn on the assembler listing. The sub-options are:
• c omit false conditionals
• d omit debugging directives
• h include high-level source
• l include assembly
• m include macro expansions
• n omit forms processing
• s include symbols
• =file set the name of the listing file
The various sub-options can be combined into a single -a option list; =file must be the last one in that
case.
Examples for assembler options passed through the C compiler
Remember that assembler options can be passed from the C compiler frontend using -Wa (see gcc_minusW
above), so in order to include the C source code into the assembler listing in file foo.lss, when
compiling foo.c, the following compiler command-line can be used:
$ avr-gcc -mmcu=atmega8 -c foo.c -o foo.o -Wa,-ahls=foo.lss
In order to pass an assembler file through the C preprocessor first, and have the assembler generate line
number debugging information for it, the following command can be used:
$ avr-gcc -c -x assembler-with-cpp -o foo.o foo.asm -Wa,--gstabs
Note that on Unix systems that have case-distinguishing file systems, specifying a file name with the
suffix .S (upper-case letter S) will make the compiler automatically assume -x assembler-with-cpp, while
using .s would pass the file directly to the assembler (no preprocessing done).
Controlling the linker avr-ld
Note
It is highly recommended to use the compiler driver avr-gcc or avr-g++ for linking.
• The driver knows which options to pass down to the linker. This includes the correct multilib path,
support libraries like libc.a, libm.a, libgcc.a and libmcu.a, as well as options for LTO (link-time
optimization) and options for plugins (that call back the compiler to compile LTO byte code),
startup code and many more.
• The driver program understands options like -llib, -Lpath, Ttext, Tdata, Tbss and -T script, so no
-Wl is required for them.
Selected linker options
A number of the standard options might be of interest to AVR users.
--defsym symbol=expr
Define a global symbol symbol using expr as the value.
-M Print a linker map to stdout.
-Map mapfile
Print a linker map to mapfile.
--cref
Output a cross reference table to the map file (in case -Map is also present), or to stdout.
--gc-sections
Only keep input sections that are referenced (by other sections or the entry symbol), and that are
not marked as KEEP in the linker script. This is used to reduce code size, usually together with
compiler option -ffunction-sections so that input section granularity is on function level rather
than on the level of compilation units.
--section-start sectionname=org
Start section sectionname at absolute address org.
--relax
Don't use this option directly or per -Wl,--relax. Instead, link with avr-gcc ... -mrelax.
Passing linker options from the C compiler
By default, all unknown non-option arguments on the avr-gcc command-line (i. e., all filename arguments
that don't have a suffix that is handled by avr-gcc) are passed straight to the linker. Thus, all files
ending in .o (object files) and .a (object libraries) are provided to the linker.
System libraries are usually not passed by their explicit filename but rather using the -l option which
uses an abbreviated form of the archive filename (see above). AVR-LibC ships system libraries, libc.a,
libm.a and libmcu.a. While the standard library libc.a will always be searched for unresolved references
when the linker is started using the C compiler frontend (i. e., there's always at least one implied -lc
option), the mathematics library libm.a is only automatically added in GCC v4.7 and above. On older
versions, it needs to be explicitly requested using -lm.
Conventionally, Makefiles use the make macro LDLIBS to keep track of -l (and possibly -L) options that
should only be appended to the C compiler command-line when linking the final binary. In contrast, the
macro LDFLAGS is used to store other command-line options to the C compiler that should be passed as
options during the linking stage. The difference is that options are placed early on the command-line,
while libraries are put at the end since they are to be used to resolve global symbols that are still
unresolved at this point.
Specific linker flags can be passed from the C compiler command-line using the -Wl compiler option, see
gcc_minusW above. This option requires that there be no spaces in the appended linker option, while some
of the linker options above (like -Map or --defsym) would require a space. In these situations, the space
can be replaced by an equal sign as well. For example, the following command-line can be used to compile
foo.c into an executable, and also produce a link map that contains a cross-reference list in the file
foo.map:
$ avr-gcc -mmcu=atmega8 foo.c -o foo.elf -Wl,-Map,foo.map -Wl,--cref
Alternatively, a comma as a placeholder will be replaced by a space before passing the option to the
linker. So for a device with external SRAM, the following command-line would cause the linker to place
the data segment at address 0x2000 in the SRAM:
$ avr-gcc -mmcu=atmega128 foo.c -o foo.elf -Wl,-Tdata,0x802000
See the explanation of the data section for why 0x800000 needs to be added to the actual value. Note that
the stack will still remain in internal RAM, through the symbol __stack that is provided by the run-time
startup code. This is probably a good idea anyway (since internal RAM access is faster), and even
required for some early devices that had hardware bugs preventing them from using a stack in external
RAM. Note also that the heap for malloc() will still be placed after all the variables in the data
section, so in this situation, no stack/heap collision can occur.
In order to relocate the stack from its default location at the top of interns RAM, the value of the
symbol __stack can be changed on the linker command-line. As the linker is typically called from the
compiler frontend, this can be achieved using a compiler option like
-Wl,--defsym=__stack=0x8003ff
The above will make the code use stack space from RAM address 0x3ff downwards. The amount of stack space
available then depends on the bottom address of internal RAM for a particular device. It is the
responsibility of the application to ensure the stack does not grow out of bounds, as well as to arrange
for the stack to not collide with variable allocations made by the compiler (sections .data and .bss).