/* 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$ */

/** \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.
The preprocessor will define the macros \c __AVR and \c __AVR__
(to the value 1) when compiling for an AVR target.  The macro
\c 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:

- <a href="https://gcc.gnu.org/onlinedocs/gcc/AVR-Options.html"
     >Current development</a> (work in progress)
- <a href="https://gcc.gnu.org/onlinedocs/gcc-14.1.0/gcc/AVR-Options.html"
     >v14</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-13.2.0/gcc/AVR-Options.html"
     >v13.2</a>,
  <a href="https://gcc.gnu.org/onlinedocs/gcc-13.3.0/gcc/AVR-Options.html"
     >v13.3</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-12.3.0/gcc/AVR-Options.html"
     >v12.3</a>,
  <a href="https://gcc.gnu.org/onlinedocs/gcc-12.4.0/gcc/AVR-Options.html"
     >v12.4</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-11.4.0/gcc/AVR-Options.html"
     >v11</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-10.5.0/gcc/AVR-Options.html"
     >v10</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-9.5.0/gcc/AVR-Options.html">v9</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-8.5.0/gcc/AVR-Options.html">v8</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-7.5.0/gcc/AVR-Options.html">v7</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-6.5.0/gcc/AVR-Options.html">v6</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-5.5.0/gcc/AVR-Options.html">v5</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-4.9.4/gcc/AVR-Options.html"
     >v4.9</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-4.8.5/gcc/AVR-Options.html"
     >v4.8</a>
- <a href="https://gcc.gnu.org/onlinedocs/gcc-4.7.4/gcc/AVR-Options.html"
     >v4.7</a>

Apart from the documentation of command line options, the linked pages also
contain:

- The documentation of
  <a href="https://gcc.gnu.org/onlinedocs/gcc/AVR-Options.html#avr-macros"
     >built-in macros</a> like \c __AVR_ARCH__, \c __AVR_ATmega328P__
  and \c __AVR_HAVE_MUL__, just to mention a few.

- How the compiler treats the
  <a href="https://gcc.gnu.org/onlinedocs/gcc/AVR-Options.html#ramp"
     >\c RAMPX, \c RAMPY, \c RAMPZ and \c RAMPD special function registers</a>
  on devices that have (one of) them.

- How the compiler treats the
  <a href="https://gcc.gnu.org/onlinedocs/gcc/AVR-Options.html#eind"
     >\c EIND special function register</a>
  on devices with more than 128 KiB of program memory,
  and how indirect calls are realized on such devices.

<dl>
<dt><tt>-mmcu=<em>arch</em></tt></dt>
<dt><tt>-mmcu=<em>mcu</em></tt></dt>
<dd>
  Compile code for architecture <tt><em>arch</em></tt> resp.
  AVR device <tt><em>mcu</em></tt>.

  Since GCC v5, the compiler no more supports indivitual devices,
  instead the compiler comes with
  <a href="https://gcc.gnu.org/wiki/avr-gcc#spec-files">device specs files</a>
  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
  <a href="https://gcc.gnu.org/wiki/avr-gcc#atpack">atpack archive</a>
  as provided by the hardware manufacturer.  Apart from the
  <tt><em>mcu</em></tt> specific specs file, it provides device headers
  <tt>io*.h</tt>, startup code <tt>crt<em>mcu</em>.o</tt> and
  device library <tt>lib<em>mcu</em>.a</tt>.
</dd>
</dl>

\subsection using_sel_gcc_opts Selected general compiler options

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

<dl>
<dt>\anchor gcc_optO<tt>-O<em>n</em></tt></dt>
<dd>
  Optimization level \e n.  Increasing \e n is meant to optimize more.

  <b>\c -O0</b>  reduces compilation time and makes debugging produce
  the expected results. This is the default.<br>
  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 <tt>\<util/delay.h\></tt> require optimization
  to be turned on.

  <b>\c -O2</b> optimizes for speed, but without enabling very expensive
  optimizations like \c -O3 does.

  <b>\c -Os</b> turns on all \c -O2 optimizations except those that often
  increase code size.  In most cases, this is the preferred optimization
  level for AVR programs.

  <b>\c -Og</b> 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.

  <b>\c -O3</b> 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.

  <b>\c -O</b> is equivalent to <b>\c -O1</b>.
  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 \ref faq_gdboptimize "appropriate FAQ entry" for
  issues regarding debugging optimized code.
</dd>
<dt>\anchor gcc_minusW<tt>-Wp,<em>preprocessor-options</em></tt></dt>
<dt><tt>-Wa,<em>assembler-options</em></tt></dt>
<dt><tt>-Wl,<em>linker-options</em></tt></dt>
<dd>
  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 \c , (comma).
</dd>

<dt>\anchor opt_g <tt>-g</tt></dt>
<dd>
  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 \c -g2 or \c -gdwarf-3.
  <br>
  The compiler may use GNU extensions to the DWARF format.
  When a debugger has problems with that, try \c -gstrict-dwarf.
</dd>

<dt>\anchor opt_x <tt>-x <em>lang</em></tt></dt>
<dt><tt>-x none</tt></dt>
<dd>
  Compile the following files in language \e lang.  Values for \e lang are:
  \c c, \c c++, \c assembler, \c assembler-with-cpp and \c none.

  For example, GCC does not recognize the <tt>.asm</tt> file extension as
  assembly source.
  With <tt>-x assembler-with-cpp file.asm</tt>, the compiler
  first runs the C preprocessor on \c file.asm (so that
  <tt>\#include \<avr/io.h\></tt> 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 <tt>-</tt> (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
  \verbatim
$ echo '#include <avr/io.h>' | avr-gcc -xc - -mmcu=atmega8 -E -dM | grep _VECTOR
  \endverbatim
  pre-processes the C file <tt>\#include \<avr/io.h\></tt> and writes all
  macro definitions to stdout.  The output is then filtered by \c grep to
  show all possible #ISR vector names for ATmega8.

  <tt>-x none</tt> returns to the default for the following inputs, i.e.
  infer the respective source languages from the file extensions.
</dd>

<dt>\anchor opt_save_temps <tt>-save-temps</tt></dt>
<dt><tt>-save-temps=obj</tt></dt>
<dt><tt>-save-temps=cwd</tt></dt>
<dt>\anchor opt_fverbose_asm <tt>-fverbose-asm</tt></dt>
<dt><tt>-dumpbase <em>base</em></tt></dt>
<dt><tt>-dumpdir <em>dir</em></tt></dt>
<dd>
  Don't remove temporary, intermediate files like C preprocessor output
  and assembly code generated by the compiler.  The intermediate
  files have file extension \c \.i (preprocessed C),
  \c \.ii (preprocessed C++) and \c \.s (preprocessed assembly,
  compiler-generated assembly).

  \c -dumpbase and \c -dumpdir can be used to adjust file names and locations.

  With \c -fverbose-asm, the compiler adds the high level source code to
  the assembly output.  Compiling without debugging information (\c -g0)
  improves legibility of the generated assembly.

  The preprocessed files can be used to check if macro expansions work as
  expected.  With \c -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 \c \#line notes.
</dd>

<dt><tt>-l<em>name</em></tt></dt>
<dd>
  Locate the archive library named <tt>lib</tt><em>name</em><tt>.a</tt>,
  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.
  \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).
</dd>

<dt><tt>-L<em>path</em></tt></dt>
<dd>
  Additional directory \e path to look for archive libraries requested by
  \c -l options.
</dd>

<dt>\anchor opt_ffunction_sections <tt>-ffunction-sections</tt></dt>
<dt>\anchor opt_fdata_sections <tt>-fdata-sections</tt></dt>
<dd>
  Put each function resp. object in static storage in its own
  \ref sec_input "input section".  This is used with
  <tt>-Wl,\--gc-sections</tt> so the linker can better garbage-collect
  unused sections, which are sections that are neither referenced by
  other sections, nor are marked as \c KEEP, nor are referenced
  by an entry symbol.
</dd>

<dt><tt>-mrelax</tt></dt>
<dd>
  Replace \c JMP and \c CALL instructions with the faster and shorter
  \c RJMP and \c RCALL instructions if possible.  That optimization is
  performed by the linker, and the assembler must not resolve some
  expressions, which is all arranged by \c -mrelax.
</dd>

<dt><tt>-Tbss <em>org</em></tt></dt>
<dt><tt>-Tdata <em>org</em></tt></dt>
<dt><tt>-Ttext <em>org</em></tt></dt>
<dd>
  Start the \c \.bss, \c \.data, or \c \.text section at VMA address \e org,
  respectively.
</dd>

<dt><tt>-T <em>scriptfile</em></tt></dt>
<dd>
  Use \e 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 \c /usr/local/avr/lib/ldscripts on Unix
  systems), and consist of the AVR architecture name (\c avr2 through
  \c avrxmega7) with the suffix \c \.x appended.
  They describe how the various \ref mem_sections "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 <a href="https://gcc.gnu.org/wiki/avr-gcc#Address_Spaces"
	>named address spaces</a>.
</dd>

<dt><tt>-nostdlib</tt></dt>
<dd>Don't link against standard libraries.</dd>

<dt><tt>-nodefaultlibs</tt></dt>
<dd>Don't link against default libraries.</dd>

<dt><tt>-nodevicelib</tt></dt>
<dd>
  Don't link against AVR-LibC's <tt>lib<em>mcu</em>.a</tt> that contains
  EEPROM support and other stuff.  This can be used when no such library
  is available.
</dd>

<dt><tt>-nostartfiles</tt></dt>
<dd>
  Don't link against AVR-LibC's \ref sec_dot_init "startup code"
  <tt>crt<em>mcu</em>.o</tt>.

  Notice that parts of the startup code are provided by <tt>libgcc.a</tt>.
  To get rid of that, one can \c -nostdlib or \c -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 \n
  <tt>-Wl,\--defsym,__do_clear_bss=0</tt> and similar for
  \c __do_copy_data, \c __do_global_ctors and \c __do_global_dtors.
</dd>

<dt><tt>-funsigned-char</tt></dt>
<dd>
  This option changes the binary interface!\n
  Make any unqualfied \c char type an unsigned char.  Without this
  option, they default to a signed char.
</dd>

<dt><tt>-funsigned-bitfields</tt></dt>
<dd>
  This option changes the binary interface!\n
  Make any unqualified bitfield type unsigned.  By default, they
  are signed.
</dd>

<dt><tt>-fshort-enums</tt></dt>
<dd>
  This option changes the binary interface!\n
  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.
</dd>

<dt><tt>-fpack-struct</tt></dt>
<dd>
  This option changes the binary interface!\n
  Pack all structure members together without holes.
</dd>

<dt><tt>-fno-jump-tables</tt></dt>
<dd>
  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.

  Note: Sinve GCC v4.9.2, tablejump code uses the \c ELPM instruction to read
  from jump tables.  In older version, use the \c -fno-jump-tables switch when
  compiling a bootloader for devices with more than 64 KiB of code memory.
</dd>

<dt><tt>-ffreestanding</tt></dt>
<dd>
  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. (In most
  cases, \c main() won't even return anyway, and hence using a return type
  of \c 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
  \c -ffreestanding, it will always call strlen() at run-time.
</dd>
</dl>

\section using_avr_as Options for the assembler avr-as

\note The preferred way to assemble a file is by means of using \c avr-gcc:
- \c 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:
<tt>-mmcu=<em>arch</em></tt>, \c -mno-skip-bug, etc.
- \c avr-gcc will call the C preprocessor on the assembler input for sources
with extensions <tt>.S</tt> and <tt>.sx</tt>.  For other extensions, use
\verbatim
$ avr-gcc -x assembler-with-cpp file.asm ...
\endverbatim
This allows to use C preprocessor directives like
\code
#include <avr/io.h>
\endcode
in assembly sources.

\subsection using_avr_as_mach_opts Machine-specific assembler options

<dl>
<dt><tt>-mmcu=</tt><em>architecture</em></dt>
<dt><tt>-mmcu=</tt><em>mcu</em></dt>
<dd>
  \c avr-as does not support all <em>mcu</em>s supported by the
  compiler.  As explained in the note above, the preferred way to run
  the assembler is by using the compiler driver \c avr-gcc.
</dd>

<dt><tt>-mall-opcodes</tt></dt>
<dd>
  Turns off opcode checking, and allows any
  possible AVR opcode to be assembled.
</dd>

<dt><tt>-mno-skip-bug</tt></dt>
<dd>
  Don't emit a warning when trying to skip a 2-word instruction
  with a <tt>CPSE/SBIC/SBIS/SBRC/SBRS</tt> instruction.  Early AVR
  devices suffered from a hardware bug where these instructions
  could not be properly skipped.
</dd>

<dt><tt>-mno-wrap</tt></dt>
<dd>
  For <tt>RJMP/RCALL</tt> instructions, don't allow the target address
  to wrap around for devices that have more than 8 KiB of memory.
</dd>

<dt><tt>\--gstabs</tt></dt>
<dd>
  Generate <tt>.stabs</tt> debugging symbols for assembler source lines.
  This enables \c avr-gdb to trace through assembler source files.  This
  option <em>must not</em> 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.
</dd>

<dt><tt>-a[cdhlmns=<em>file</em>]</tt></dt>
<dd>
  Turn on the assembler listing.  The sub-options are:
  <ul>
    <li>\c c     omit false conditionals</li>
    <li>\c d     omit debugging directives</li>
    <li>\c h     include high-level source</li>
    <li>\c l     include assembly</li>
    <li>\c m     include macro expansions</li>
    <li>\c n     omit forms processing</li>
    <li>\c s     include symbols</li>
    <li><tt>=<em>file</em></tt>  set the name of the listing file</li>
  </ul>
  The various sub-options can be combined into a single \c -a option
  list; \e =file must be the last one in that case.
</dd>
</dl>

\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.lss, when compiling \c foo.c, the following compiler command-line
can be used:

\verbatim
$ avr-gcc -mmcu=atmega8 -c foo.c -o foo.o -Wa,-ahls=foo.lss
\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.asm -Wa,--gstabs
\endverbatim

Note that on Unix systems that have case-distinguishing file systems,
specifying a file name with the suffix <tt>.S</tt> (upper-case letter \c S)
will make the compiler automatically assume <tt>-x assembler-with-cpp</tt>,
while using <tt>.s</tt> would pass the file directly to the assembler (no
preprocessing done).

\section using_avr_ld Controlling the linker avr-ld

\note It is highly recommended to use the compiler driver \c avr-gcc
or \c avr-g++ for linking.
- The driver knows which options to pass down to the linker. This includes
the correct multilib path, support libraries like \c libc.a, \c libm.a,
\c libgcc.a and <tt>lib<em>mcu</em>.a</tt>, 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 <tt>-l<em>lib</em></tt>,
<tt>-L<em>path</em></tt>, \c Ttext, \c Tdata, \c Tbss and
<tt>-T <em>script</em></tt>, so no \c -Wl is required for them.

\subsection using_sel_ld_opts Selected linker options

A number of the standard options might be of interest to AVR users.

<dl>
<dt>\anchor opt_defsym <tt>\--defsym <em>symbol=expr</em></tt></dt>
<dd>Define a global symbol \e symbol using \e expr as the value.</dd>

<dt><tt>-M</tt></dt>
<dd>Print a linker map to \c stdout.</dd>

<dt><tt>-Map <em>mapfile</em></tt></dt>
<dd>Print a linker map to \e mapfile.</dd>

<dt><tt>\--cref</tt></dt>
<dd>
  Output a cross reference table to the map file (in case \c -Map is
  also present), or to \c stdout.
</dd>

<dt><tt>\--gc-sections</tt></dt>
<dd>
  Only keep input sections that are referenced (by other sections or the
  entry symbol), and that are not marked as \c KEEP in the linker script.
  This is used to reduce code size, usually together with compiler option
  \c -ffunction-sections so that input section granularity is on function
  level rather than on the level of compilation units.
</dd>

<dt><tt>\--section-start <em>sectionname=org</em></tt></dt>
<dd>Start section \e sectionname at absolute address \e org.</dd>

<dt><tt>\--relax</tt></dt>
<dd>
  Don't use this option directly or per <tt>-Wl,\--relax</tt>.
  Instead, link with <tt>avr-gcc ... -mrelax</tt>.
</dd>
</dl>

\subsection using_pass_ld_opts Passing linker options from the C compiler

By default, all unknown non-option arguments on the \c avr-gcc
command-line (i. e., all filename arguments that don't have a suffix
that is handled by \c 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 system libraries,
\c libc.a, \c libm.a and <tt>lib<em>mcu</em>.a</tt>.
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
is only automatically added in GCC v4.7 and above.  On older versions, it
needs to be explicitly requested using \c -lm.

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 -mmcu=atmega8 foo.c -o foo.elf -Wl,-Map,foo.map -Wl,--cref
\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 foo.c -o foo.elf -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).

*/
