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.

Selected general compiler options

The following general gcc options might be of some interest to AVR users.

Options for the assembler avr-as

Machine-specific assembler options

Examples for assembler options passed through the C compiler

Remember that assembler options can be passed from the C compiler frontend using -Wa (see above), so in order to include the C source code into the assembler listing in file foo.lst, when compiling foo.c, the following compiler command-line can be used:

        $ avr-gcc -c -O foo.c -o foo.o -Wa,-ahls=foo.lst

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.S -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

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.

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 two system libraries, libc.a, and libm.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 needs to be explicitly requested using -lm. See also the entry in the FAQ explaining this.

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 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 -O -o foo.out -Wl,-Map=foo.map -Wl,--cref foo.c

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 -o foo.out -Wl,-Tdata,0x802000

See the explanation of the data section for why 0x800000 needs to be added to the actual value. Note that unless a -minit-stack option has been given when compiling the C source file that contains the function main(), 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.


Automatically generated by Doxygen 1.2.18 on 26 Nov 2003.