/* Copyright (c) 2002,2004,2005,2006,2007 Joerg Wunsch All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the copyright holders nor the names of contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /* $Id: using-tools.dox,v 1.39.2.2 2007/12/21 20:44:04 joerg_wunsch Exp $ */ /** \page 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 \c texinfo files. Command-line options are explained in detail in the manual page. \section using_avr_gcc Options for the C compiler avr-gcc \subsection using_avr_gcc_mach_opt Machine-specific options for the AVR The following machine-specific options are recognized by the C compiler frontend. In addition to the preprocessor macros indicated in the tables below, 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 when using the standard levels gnu89 (default) and gnu99 but not with c89 and c99. - -mmcu=architecture

Compile code for \e architecture. Currently known architectures are

Architecture Macros Description
avr1 __AVR_ARCH__=1
__AVR_ASM_ONLY__
__AVR_2_BYTE_PC__ [2] 		Simple CPU core, only assembler support
avr2 __AVR_ARCH__=2
__AVR_2_BYTE_PC__ [2] 		"Classic" CPU core, up to 8 KB of ROM
avr25 [1] __AVR_ARCH__=25
__AVR_HAVE_MOVW__ [1]
__AVR_HAVE_LPMX__ [1]
__AVR_2_BYTE_PC__ [2] 		"Classic" CPU core with 'MOVW' and 'LPM Rx, Z[+]' instruction, up to 8 KB of ROM
avr3 __AVR_ARCH__=3
__AVR_MEGA__
__AVR_2_BYTE_PC__ [2] 		"Classic" CPU core, 16 KB to 128 KB of ROM
avr4 __AVR_ARCH__=4
__AVR_ENHANCED__
__AVR_HAVE_MOVW__ [1]
__AVR_HAVE_LPMX__ [1]
__AVR_HAVE_MUL__ [1]
__AVR_2_BYTE_PC__ [2] 		"Enhanced" CPU core, up to 8 KB of ROM
avr5 __AVR_ARCH__=5
__AVR_MEGA__
__AVR_ENHANCED__
__AVR_HAVE_MOVW__ [1]
__AVR_HAVE_LPMX__ [1]
__AVR_HAVE_MUL__ [1]
__AVR_2_BYTE_PC__ [2] 		"Enhanced" CPU core, 16 KB to 128 KB of ROM
avr6 [2] __AVR_ARCH__=6
__AVR_MEGA__
__AVR_ENHANCED__
__AVR_HAVE_MOVW__ [1]
__AVR_HAVE_LPMX__ [1]
__AVR_HAVE_MUL__ [1]
__AVR_3_BYTE_PC__ [2] 		"Enhanced" CPU core, 256 KB of ROM

[1] New in GCC 4.2
[2] Unofficial patch for GCC 4.1

By default, code is generated for the avr2 architecture.

Note that when only using -mmcu=architecture but no -mmcu=MCU type, including the file <avr/io.h> cannot work since it cannot decide which device's definitions to select.

- -mmcu=MCU type

The following MCU types are currently understood by avr-gcc. The table matches them against the corresponding avr-gcc architecture name, and shows the preprocessor symbol declared by the \c -mmcu option.

ArchitectureMCU nameMacro
avr1at90s1200__AVR_AT90S1200__
avr1attiny11__AVR_ATtiny11__
avr1attiny12__AVR_ATtiny12__
avr1attiny15__AVR_ATtiny15__
avr1attiny28__AVR_ATtiny28__
avr2at90s2313__AVR_AT90S2313__
avr2at90s2323__AVR_AT90S2323__
avr2at90s2333__AVR_AT90S2333__
avr2at90s2343__AVR_AT90S2343__
avr2attiny22__AVR_ATtiny22__
avr2attiny26__AVR_ATtiny26__
avr2at90s4414__AVR_AT90S4414__
avr2at90s4433__AVR_AT90S4433__
avr2at90s4434__AVR_AT90S4434__
avr2at90s8515__AVR_AT90S8515__
avr2at90c8534__AVR_AT90C8534__
avr2at90s8535__AVR_AT90S8535__
avr2/avr25 [1]at86rf401__AVR_AT86RF401__
avr2/avr25 [1]attiny13__AVR_ATtiny13__
avr2/avr25 [1]attiny2313__AVR_ATtiny2313__
avr2/avr25 [1]attiny24__AVR_ATtiny24__
avr2/avr25 [1]attiny25__AVR_ATtiny25__
avr2/avr25 [1]attiny261__AVR_ATtiny261__
avr2/avr25 [1]attiny43u__AVR_ATtiny43U__
avr2/avr25 [1]attiny44__AVR_ATtiny44__
avr2/avr25 [1]attiny45__AVR_ATtiny45__
avr2/avr25 [1]attiny461__AVR_ATtiny461__
avr2/avr25 [1]attiny48__AVR_ATtiny48__
avr2/avr25 [1]attiny84__AVR_ATtiny84__
avr2/avr25 [1]attiny85__AVR_ATtiny85__
avr2/avr25 [1]attiny861__AVR_ATtiny861__
avr2/avr25 [1]attiny88__AVR_ATtiny88__
avr3atmega103__AVR_ATmega103__
avr3atmega603__AVR_ATmega603__
avr3at43usb320__AVR_AT43USB320__
avr3at43usb355__AVR_AT43USB355__
avr3at76c711__AVR_AT76C711__
avr4atmega48__AVR_ATmega48__
avr4atmega48p__AVR_ATmega48P__
avr4atmega8__AVR_ATmega8__
avr4atmega8515__AVR_ATmega8515__
avr4atmega8535__AVR_ATmega8535__
avr4atmega88__AVR_ATmega88__
avr4atmega88p__AVR_ATmega88P__
avr4atmega8hva__AVR_ATmega8HVA__
avr4at90pwm1__AVR_AT90PWM1__
avr4at90pwm2__AVR_AT90PWM2__
avr4at90pwm2b__AVR_AT90PWM2B__
avr4at90pwm3__AVR_AT90PWM3__
avr4at90pwm3b__AVR_AT90PWM3B__
avr5at90pwm216__AVR_AT90PWM216__
avr5at90pwm316__AVR_AT90PWM316__
avr5at90can32__AVR_AT90CAN32__
avr5at90can64__AVR_AT90CAN64__
avr5at90can128__AVR_AT90CAN128__
avr5at90usb82__AVR_AT90USB82__
avr5at90usb162__AVR_AT90USB162__
avr5at90usb646__AVR_AT90USB646__
avr5at90usb647__AVR_AT90USB647__
avr5at90usb1286__AVR_AT90USB1286__
avr5at90usb1287__AVR_AT90USB1287__
avr5atmega128__AVR_ATmega128__
avr5atmega1280__AVR_ATmega1280__
avr5atmega1281__AVR_ATmega1281__
avr5atmega1284p__AVR_ATmega1284P__
avr5atmega16__AVR_ATmega16__
avr5atmega161__AVR_ATmega161__
avr5atmega162__AVR_ATmega162__
avr5atmega163__AVR_ATmega163__
avr5atmega164p__AVR_ATmega164P__
avr5atmega165__AVR_ATmega165__
avr5atmega165p__AVR_ATmega165P__
avr5atmega168__AVR_ATmega168__
avr5atmega168p__AVR_ATmega168P__
avr5atmega169__AVR_ATmega169__
avr5atmega169p__AVR_ATmega169P__
avr5atmega16hva__AVR_ATmega16HVA__
avr5atmega32__AVR_ATmega32__
avr5atmega323__AVR_ATmega323__
avr5atmega324p__AVR_ATmega324P__
avr5atmega325__AVR_ATmega325__
avr5atmega325p__AVR_ATmega325P__
avr5atmega3250__AVR_ATmega3250__
avr5atmega3250p__AVR_ATmega3250P__
avr5atmega328p__AVR_ATmega328P__
avr5atmega329__AVR_ATmega329__
avr5atmega329p__AVR_ATmega329P__
avr5atmega3290__AVR_ATmega3290__
avr5atmega3290p__AVR_ATmega3290P__
avr5atmega32hvb__AVR_ATmega32HVB__
avr5atmega406__AVR_ATmega406__
avr5atmega64__AVR_ATmega64__
avr5atmega640__AVR_ATmega640__
avr5atmega644__AVR_ATmega644__
avr5atmega644p__AVR_ATmega644P__
avr5atmega645__AVR_ATmega645__
avr5atmega6450__AVR_ATmega6450__
avr5atmega649__AVR_ATmega649__
avr5atmega6490__AVR_ATmega6490__
avr5at94k__AVR_AT94K__
avr6atmega2560__AVR_ATmega2560__
avr6atmega2561__AVR_ATmega2561__

[1] 'avr25' architecture is new in GCC 4.2

- \c -morder1 - \c -morder2

Change the order of register assignment. The default is

r24, r25, r18, r19, r20, r21, r22, r23, r30, r31, r26, r27, r28, r29, r17, r16, r15, r14, r13, r12, r11, r10, r9, r8, r7, r6, r5, r4, r3, r2, r0, r1

Order 1 uses

r18, r19, r20, r21, r22, r23, r24, r25, r30, r31, r26, r27, r28, r29, r17, r16, r15, r14, r13, r12, r11, r10, r9, r8, r7, r6, r5, r4, r3, r2, r0, r1

Order 2 uses

r25, r24, r23, r22, r21, r20, r19, r18, r30, r31, r26, r27, r28, r29, r17, r16, r15, r14, r13, r12, r11, r10, r9, r8, r7, r6, r5, r4, r3, r2, r1, r0

- \c -mint8

Assume \c int to be an 8-bit integer. Note that this is not really supported by \c avr-libc, so it should normally not be used. The default is to use 16-bit integers.

- \c -mno-interrupts

Generates code that changes the stack pointer without disabling interrupts. Normally, the state of the status register \c SREG is saved in a temporary register, interrupts are disabled while changing the stack pointer, and \c SREG is restored.

Specifying this option will define the preprocessor macro \c __NO_INTERRUPTS__ to the value 1.

- \c -mcall-prologues

Use subroutines for function prologue/epilogue. For complex functions that use many registers (that needs to be saved/restored on function entry/exit), this saves some space at the cost of a slightly increased execution time.

- \c -mtiny-stack

Change only the low 8 bits of the stack pointer.

- \c -mno-tablejump

Do not generate tablejump instructions. By default, jump tables can be used to optimize \c 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 \c switch statements where most of the jumps would go to the default label, they might waste a bit of flash memory.

- \c -mshort-calls

Use \c rjmp/rcall (limited range) on >8K devices. On \c avr2 and \c avr4 architectures (less than 8 KB or flash memory), this is always the case. On \c avr3 and \c avr5 architectures, calls and jumps to targets outside the current function will by default use \c jmp/call instructions that can cover the entire address range, but that require more flash ROM and execution time.

- \c -mrtl

Dump the internal compilation result called "RTL" into comments in the generated assembler code. Used for debugging avr-gcc.

- \c -msize

Dump the address, size, and relative cost of each statement into comments in the generated assembler code. Used for debugging avr-gcc.

- \c -mdeb

Generate lots of debugging information to \c stderr.

\subsection using_sel_gcc_opts Selected general compiler options The following general gcc options might be of some interest to AVR users. - -On

\anchor gcc_optO Optimization level \e n. Increasing \e n is meant to optimize more, an optimization level of 0 means no optimization at all, which is the default if no \c -O option is present. The special option \c -Os is meant to turn on all \c -O2 optimizations that are not expected to increase code size.

Note that at \c -O3, gcc attempts to inline all "simple" functions. For the AVR target, this will normally constitute a large pessimization due to the code increasement. The only other optimization turned on with \c -O3 is \c -frename-registers, which could rather be enabled manually instead.

A simple \c -O option is equivalent to \c -O1.

Note also that 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).

See also the \ref faq_gdboptimize "appropriate FAQ entry" for issues regarding debugging optimized code.

- -Wa,assembler-options - -Wl,linker-options

\anchor gcc_minusW Pass the listed options to the assembler, or linker, respectively.

- \c -g

Generate debugging information that can be used by avr-gdb.

- \c -ffreestanding

Assume a "freestanding" environment as per the C standard. This turns off automatic builtin functions (though they can still be reached by prepending \c __builtin_ to the actual function name). It also makes the compiler not complain when \c main() is declared with a \c void return type which makes some sense in a microcontroller environment where the application cannot meaningfully provide a return value to its environment (in most cases, \c main() won't even return anyway). However, this 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. E. g., 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 \c -ffreestanding, it will always call strlen() at run-time.

- \c -funsigned-char

Make any unqualfied \c char type an unsigned char. Without this option, they default to a signed char.

- \c -funsigned-bitfields

Make any unqualified bitfield type unsigned. By default, they are signed.

- \c -fshort-enums

Allocate to an \c 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.

- \c -fpack-struct

Pack all structure members together without holes.

\section using_avr_as Options for the assembler avr-as \subsection using_avr_as_mach_opts Machine-specific assembler options - -mmcu=architecture - -mmcu=MCU name

avr-as understands the same \c -mmcu= options as \ref using_avr_gcc "avr-gcc". By default, avr2 is assumed, but this can be altered by using the appropriate \c .arch pseudo-instruction inside the assembler source file.

- \c -mall-opcodes

Turns off opcode checking for the actual MCU type, and allows any possible AVR opcode to be assembled.

- \c -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.

- \c -mno-wrap

For RJMP/RCALL instructions, don't allow the target address to wrap around for devices that have more than 8 KB of memory.

- \c --gstabs

Generate \c .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:

The various sub-options can be combined into a single \c -a option list; \e =file must be the last one in that case.

\subsection using_avr_example Examples for assembler options passed through the C compiler Remember that assembler options can be passed from the C compiler frontend using \c -Wa (see \ref gcc_minusW "above"), so in order to include the C source code into the assembler listing in file \c foo.lst, when compiling \c foo.c, the following compiler command-line can be used: \verbatim $ avr-gcc -c -O foo.c -o foo.o -Wa,-ahls=foo.lst \endverbatim 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: \verbatim $ avr-gcc -c -x assembler-with-cpp -o foo.o foo.S -Wa,--gstabs \endverbatim Note that on Unix systems that have case-distinguishing file systems, specifying a file name with the suffix \c .S (upper-case letter S) will make the compiler automatically assume -x assembler-with-cpp, while using \c .s would pass the file directly to the assembler (no preprocessing done). \section using_avr_ld Controlling the linker avr-ld \subsection using_sel_ld_opts Selected linker options While there are no machine-specific options for avr-ld, a number of the standard options might be of interest to AVR users. - -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 compile time (e. g. \c /usr/local/avr/lib on Unix systems), possibly extended by pathname entries as specified by \c -L options (that must precede the \c -l options on the command-line).

- -Lpath

Additional location to look for archive libraries requested by \c -l options.

- --defsym symbol=expr

Define a global symbol \e symbol using \e expr as the value.

- \c -M

Print a linker map to \c stdout.

- -Map mapfile

Print a linker map to \e mapfile.

- \c --cref

Output a cross reference table to the map file (in case \c -Map is also present), or to \c stdout.

- --section-start sectionname=org

Start section \e sectionname at absolute address \e org.

- -Tbss org - -Tdata org - -Ttext org

Start the \c bss, \c data, or \c text section at \e org, respectively.

- -T scriptfile

Use \e scriptfile as the linker script, replacing the default linker script. Default linker scripts are stored in a system-specific location (e. g. under \c /usr/local/avr/lib/ldscripts on Unix systems), and consist of the AVR architecture name (avr2 through avr5) with the suffix \c .x appended. They describe how the various \ref mem_sections "memory sections" will be linked together.

\subsection using_pass_ld_opts 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 \c .o (object files) and \c .a (object libraries) are provided to the linker. System libraries are usually not passed by their explicit filename but rather using the \c -l option which uses an abbreviated form of the archive filename (see above). avr-libc ships two system libraries, \c libc.a, and \c libm.a. While the standard library \c 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 \c -lc option), the mathematics library \c libm.a needs to be explicitly requested using \c -lm. See also the \ref faq_libm "entry in the FAQ" explaining this. Conventionally, Makefiles use the \c make macro \c LDLIBS to keep track of \c -l (and possibly \c -L) options that should only be appended to the C compiler command-line when linking the final binary. In contrast, the macro \c 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 \c -Wl compiler option, see \ref gcc_minusW "above". This option requires that there be no spaces in the appended linker option, while some of the linker options above (like \c -Map or \c --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 \c foo.c into an executable, and also produce a link map that contains a cross-reference list in the file \c foo.map: \verbatim $ avr-gcc -O -o foo.out -Wl,-Map=foo.map -Wl,--cref foo.c \endverbatim 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: \verbatim $ avr-gcc -mmcu=atmega128 -o foo.out -Wl,-Tdata,0x802000 \endverbatim See the explanation of the \ref sec_dot_data "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 \c __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 \c 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 \c __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 \code -Wl,--defsym=__stack=0x8003ff \endcode 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). */