e following methods in order, and
stopping when one of them succeeds:
   * the `-e' ENTRY command-line option;

   * the `ENTRY(SYMBOL)' command in a linker script;

   * the value of a target specific symbol, if it is defined;  For many
     targets this is `start', but PE and BeOS based systems for example
     check a list of possible entry symbols, matching the first one
     found.

   * the address of the first byte of the `.text' section, if present;

   * The address `0'.


File: ld.info,  Node: File Commands,  Next: Format Commands,  Prev: Entry Point,  Up: Simple Commands

3.4.2 Commands Dealing with Files
---------------------------------

Several linker script commands deal with files.

`INCLUDE FILENAME'
     Include the linker script FILENAME at this point.  The file will
     be searched for in the current directory, and in any directory
     specified with the `-L' option.  You can nest calls to `INCLUDE'
     up to 10 levels deep.

     You can place `INCLUDE' directives at the top level, in `MEMORY' or
     `SECTIONS' commands, or in output section descriptions.

`INPUT(FILE, FILE, ...)'
`INPUT(FILE FILE ...)'
     The `INPUT' command directs the linker to include the named files
     in the link, as though they were named on the command line.

     For example, if you always want to include `subr.o' any time you do
     a link, but you can't be bothered to put it on every link command
     line, then you can put `INPUT (subr.o)' in your linker script.

     In fact, if you like, you can list all of your input files in the
     linker script, and then invoke the linker with nothing but a `-T'
     option.

     In case a "sysroot prefix" is configured, and the filename starts
     with the `/' character, and the script being processed was located
     inside the "sysroot prefix", the filename will be looked for in
     the "sysroot prefix".  Otherwise, the linker will try to open the
     file in the current directory.  If it is not found, the linker
     will search through the archive library search path.  See the
     description of `-L' in *Note Command Line Options: Options.

     If you use `INPUT (-lFILE)', `ld' will transform the name to
     `libFILE.a', as with the command line argument `-l'.

     When you use the `INPUT' command in an implicit linker script, the
     files will be included in the link at the point at which the linker
     script file is included.  This can affect archive searching.

`GROUP(FILE, FILE, ...)'
`GROUP(FILE FILE ...)'
     The `GROUP' command is like `INPUT', except that the named files
     should all be archives, and they are searched repeatedly until no
     new undefined references are created.  See the description of `-('
     in *Note Command Line Options: Options.

`AS_NEEDED(FILE, FILE, ...)'
`AS_NEEDED(FILE FILE ...)'
     This construct can appear only inside of the `INPUT' or `GROUP'
     commands, among other filenames.  The files listed will be handled
     as if they appear directly in the `INPUT' or `GROUP' commands,
     with the exception of ELF shared libraries, that will be added only
     when they are actually needed.  This construct essentially enables
     `--as-needed' option for all the files listed inside of it and
     restores previous `--as-needed' resp. `--no-as-needed' setting
     afterwards.

`OUTPUT(FILENAME)'
     The `OUTPUT' command names the output file.  Using
     `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
     FILENAME' on the command line (*note Command Line Options:
     Options.).  If both are used, the command line option takes
     precedence.

     You can use the `OUTPUT' command to define a default name for the
     output file other than the usual default of `a.out'.

`SEARCH_DIR(PATH)'
     The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
     looks for archive libraries.  Using `SEARCH_DIR(PATH)' is exactly
     like using `-L PATH' on the command line (*note Command Line
     Options: Options.).  If both are used, then the linker will search
     both paths.  Paths specified using the command line option are
     searched first.

`STARTUP(FILENAME)'
     The `STARTUP' command is just like the `INPUT' command, except
     that FILENAME will become the first input file to be linked, as
     though it were specified first on the command line.  This may be
     useful when using a system in which the entry point is always the
     start of the first file.


File: ld.info,  Node: Format Commands,  Next: REGION_ALIAS,  Prev: File Commands,  Up: Simple Commands

3.4.3 Commands Dealing with Object File Formats
-----------------------------------------------

A couple of linker script commands deal with object file formats.

`OUTPUT_FORMAT(BFDNAME)'
`OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
     The `OUTPUT_FORMAT' command names the BFD format to use for the
     output file (*note BFD::).  Using `OUTPUT_FORMAT(BFDNAME)' is
     exactly like using `--oformat BFDNAME' on the command line (*note
     Command Line Options: Options.).  If both are used, the command
     line option takes precedence.

     You can use `OUTPUT_FORMAT' with three arguments to use different
     formats based on the `-EB' and `-EL' command line options.  This
     permits the linker script to set the output format based on the
     desired endianness.

     If neither `-EB' nor `-EL' are used, then the output format will
     be the first argument, DEFAULT.  If `-EB' is used, the output
     format will be the second argument, BIG.  If `-EL' is used, the
     output format will be the third argument, LITTLE.

     For example, the default linker script for the MIPS ELF target
     uses this command:
          OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
     This says that the default format for the output file is
     `elf32-bigmips', but if the user uses the `-EL' command line
     option, the output file will be created in the `elf32-littlemips'
     format.

`TARGET(BFDNAME)'
     The `TARGET' command names the BFD format to use when reading input
     files.  It affects subsequent `INPUT' and `GROUP' commands.  This
     command is like using `-b BFDNAME' on the command line (*note
     Command Line Options: Options.).  If the `TARGET' command is used
     but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
     used to set the format for the output file.  *Note BFD::.


File: ld.info,  Node: REGION_ALIAS,  Next: Miscellaneous Commands,  Prev: Format Commands,  Up: Simple Commands

3.4.4 Assign alias names to memory regions
------------------------------------------

Alias names can be added to existing memory regions created with the
*Note MEMORY:: command.  Each name corresponds to at most one memory
region.

     REGION_ALIAS(ALIAS, REGION)

   The `REGION_ALIAS' function creates an alias name ALIAS for the
memory region REGION.  This allows a flexible mapping of output sections
to memory regions.  An example follows.

   Suppose we have an application for embedded systems which come with
various memory storage devices.  All have a general purpose, volatile
memory `RAM' that allows code execution or data storage.  Some may have
a read-only, non-volatile memory `ROM' that allows code execution and
read-only data access.  The last variant is a read-only, non-volatile
memory `ROM2' with read-only data access and no code execution
capability.  We have four output sections:

   * `.text' program code;

   * `.rodata' read-only data;

   * `.data' read-write initialized data;

   * `.bss' read-write zero initialized data.

   The goal is to provide a linker command file that contains a system
independent part defining the output sections and a system dependent
part mapping the output sections to the memory regions available on the
system.  Our embedded systems come with three different memory setups
`A', `B' and `C':
Section            Variant A          Variant B          Variant C
.text              RAM                ROM                ROM
.rodata            RAM                ROM                ROM2
.data              RAM                RAM/ROM            RAM/ROM2
.bss               RAM                RAM                RAM
   The notation `RAM/ROM' or `RAM/ROM2' means that this section is
loaded into region `ROM' or `ROM2' respectively.  Please note that the
load address of the `.data' section starts in all three variants at the
end of the `.rodata' section.

   The base linker script that deals with the output sections follows.
It includes the system dependent `linkcmds.memory' file that describes
the memory layout:
     INCLUDE linkcmds.memory

     SECTIONS
       {
         .text :
           {
             *(.text)
           } > REGION_TEXT
         .rodata :
           {
             *(.rodata)
             rodata_end = .;
           } > REGION_RODATA
         .data : AT (rodata_end)
           {
             data_start = .;
             *(.data)
           } > REGION_DATA
         data_size = SIZEOF(.data);
         data_load_start = LOADADDR(.data);
         .bss :
           {
             *(.bss)
           } > REGION_BSS
       }

   Now we need three different `linkcmds.memory' files to define memory
regions and alias names.  The content of `linkcmds.memory' for the three
variants `A', `B' and `C':
`A'
     Here everything goes into the `RAM'.
          MEMORY
            {
              RAM : ORIGIN = 0, LENGTH = 4M
            }

          REGION_ALIAS("REGION_TEXT", RAM);
          REGION_ALIAS("REGION_RODATA", RAM);
          REGION_ALIAS("REGION_DATA", RAM);
          REGION_ALIAS("REGION_BSS", RAM);

`B'
     Program code and read-only data go into the `ROM'.  Read-write
     data goes into the `RAM'.  An image of the initialized data is
     loaded into the `ROM' and will be copied during system start into
     the `RAM'.
          MEMORY
            {
              ROM : ORIGIN = 0, LENGTH = 3M
              RAM : ORIGIN = 0x10000000, LENGTH = 1M
            }

          REGION_ALIAS("REGION_TEXT", ROM);
          REGION_ALIAS("REGION_RODATA", ROM);
          REGION_ALIAS("REGION_DATA", RAM);
          REGION_ALIAS("REGION_BSS", RAM);

`C'
     Program code goes into the `ROM'.  Read-only data goes into the
     `ROM2'.  Read-write data goes into the `RAM'.  An image of the
     initialized data is loaded into the `ROM2' and will be copied
     during system start into the `RAM'.
          MEMORY
            {
              ROM : ORIGIN = 0, LENGTH = 2M
              ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
              RAM : ORIGIN = 0x20000000, LENGTH = 1M
            }

          REGION_ALIAS("REGION_TEXT", ROM);
          REGION_ALIAS("REGION_RODATA", ROM2);
          REGION_ALIAS("REGION_DATA", RAM);
          REGION_ALIAS("REGION_BSS", RAM);

   It is possible to write a common system initialization routine to
copy the `.data' section from `ROM' or `ROM2' into the `RAM' if
necessary:
     #include <string.h>

     extern char data_start [];
     extern char data_size [];
     extern char data_load_start [];

     void copy_data(void)
     {
       if (data_start != data_load_start)
         {
           memcpy(data_start, data_load_start, (size_t) data_size);
         }
     }


File: ld.info,  Node: Miscellaneous Commands,  Prev: REGION_ALIAS,  Up: Simple Commands

3.4.5 Other Linker Script Commands
----------------------------------

There are a few other linker scripts commands.

`ASSERT(EXP, MESSAGE)'
     Ensure that EXP is non-zero.  If it is zero, then exit the linker
     with an error code, and print MESSAGE.

`EXTERN(SYMBOL SYMBOL ...)'
     Force SYMBOL to be entered in the output file as an undefined
     symbol.  Doing this may, for example, trigger linking of additional
     modules from standard libraries.  You may list several SYMBOLs for
     each `EXTERN', and you may use `EXTERN' multiple times.  This
     command has the same effect as the `-u' command-line option.

`FORCE_COMMON_ALLOCATION'
     This command has the same effect as the `-d' command-line option:
     to make `ld' assign space to common symbols even if a relocatable
     output file is specified (`-r').

`INHIBIT_COMMON_ALLOCATION'
     This command has the same effect as the `--no-define-common'
     command-line option: to make `ld' omit the assignment of addresses
     to common symbols even for a non-relocatable output file.

`INSERT [ AFTER | BEFORE ] OUTPUT_SECTION'
     This command is typically used in a script specified by `-T' to
     augment the default `SECTIONS' with, for example, overlays.  It
     inserts all prior linker script statements after (or before)
     OUTPUT_SECTION, and also causes `-T' to not override the default
     linker script.  The exact insertion point is as for orphan
     sections.  *Note Location Counter::.  The insertion happens after
     the linker has mapped input sections to output sections.  Prior to
     the insertion, since `-T' scripts are parsed before the default
     linker script, statements in the `-T' script occur before the
     default linker script statements in the internal linker
     representation of the script.  In particular, input section
     assignments will be made to `-T' output sections before those in
     the default script.  Here is an example of how a `-T' script using
     `INSERT' might look:

          SECTIONS
          {
            OVERLAY :
            {
              .ov1 { ov1*(.text) }
              .ov2 { ov2*(.text) }
            }
          }
          INSERT AFTER .text;

`NOCROSSREFS(SECTION SECTION ...)'
     This command may be used to tell `ld' to issue an error about any
     references among certain output sections.

     In certain types of programs, particularly on embedded systems when
     using overlays, when one section is loaded into memory, another
     section will not be.  Any direct references between the two
     sections would be errors.  For example, it would be an error if
     code in one section called a function defined in the other section.

     The `NOCROSSREFS' command takes a list of output section names.  If
     `ld' detects any cross references between the sections, it reports
     an error and returns a non-zero exit status.  Note that the
     `NOCROSSREFS' command uses output section names, not input section
     names.

`OUTPUT_ARCH(BFDARCH)'
     Specify a particular output machine architecture.  The argument is
     one of the names used by the BFD library (*note BFD::).  You can
     see the architecture of an object file by using the `objdump'
     program with the `-f' option.


File: ld.info,  Node: Assignments,  Next: SECTIONS,  Prev: Simple Commands,  Up: Scripts

3.5 Assigning Values to Symbols
===============================

You may assign a value to a symbol in a linker script.  This will define
the symbol and place it into the symbol table with a global scope.

* Menu:

* Simple Assignments::		Simple Assignments
* PROVIDE::			PROVIDE
* PROVIDE_HIDDEN::		PROVIDE_HIDDEN
* Source Code Reference::	How to use a linker script defined symbol in source code


File: ld.info,  Node: Simple Assignments,  Next: PROVIDE,  Up: Assignments

3.5.1 Simple Assignments
------------------------

You may assign to a symbol using any of the C assignment operators:

`SYMBOL = EXPRESSION ;'
`SYMBOL += EXPRESSION ;'
`SYMBOL -= EXPRESSION ;'
`SYMBOL *= EXPRESSION ;'
`SYMBOL /= EXPRESSION ;'
`SYMBOL <<= EXPRESSION ;'
`SYMBOL >>= EXPRESSION ;'
`SYMBOL &= EXPRESSION ;'
`SYMBOL |= EXPRESSION ;'

   The first case will define SYMBOL to the value of EXPRESSION.  In
the other cases, SYMBOL must already be defined, and the value will be
adjusted accordingly.

   The special symbol name `.' indicates the location counter.  You may
only use this within a `SECTIONS' command.  *Note Location Counter::.

   The semicolon after EXPRESSION is required.

   Expressions are defined below; see *Note Expressions::.

   You may write symbol assignments as commands in their own right, or
as statements within a `SECTIONS' command, or as part of an output
section description in a `SECTIONS' command.

   The section of the symbol will be set from the section of the
expression; for more information, see *Note Expression Section::.

   Here is an example showing the three different places that symbol
assignments may be used:

     floating_point = 0;
     SECTIONS
     {
       .text :
         {
           *(.text)
           _etext = .;
         }
       _bdata = (. + 3) & ~ 3;
       .data : { *(.data) }
     }
   In this example, the symbol `floating_point' will be defined as
zero.  The symbol `_etext' will be defined as the address following the
last `.text' input section.  The symbol `_bdata' will be defined as the
address following the `.text' output section aligned upward to a 4 byte
boundary.


File: ld.info,  Node: PROVIDE,  Next: PROVIDE_HIDDEN,  Prev: Simple Assignments,  Up: Assignments

3.5.2 PROVIDE
-------------

In some cases, it is desirable for a linker script to define a symbol
only if it is referenced and is not defined by any object included in
the link.  For example, traditional linkers defined the symbol `etext'.
However, ANSI C requires that the user be able to use `etext' as a
function name without encountering an error.  The `PROVIDE' keyword may
be used to define a symbol, such as `etext', only if it is referenced
but not defined.  The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.

   Here is an example of using `PROVIDE' to define `etext':
     SECTIONS
     {
       .text :
         {
           *(.text)
           _etext = .;
           PROVIDE(etext = .);
         }
     }

   In this example, if the program defines `_etext' (with a leading
underscore), the linker will give a multiple definition error.  If, on
the other hand, the program defines `etext' (with no leading
underscore), the linker will silently use the definition in the program.
If the program references `etext' but does not define it, the linker
will use the definition in the linker script.


File: ld.info,  Node: PROVIDE_HIDDEN,  Next: Source Code Reference,  Prev: PROVIDE,  Up: Assignments

3.5.3 PROVIDE_HIDDEN
--------------------

Similar to `PROVIDE'.  For ELF targeted ports, the symbol will be
hidden and won't be exported.


File: ld.info,  Node: Source Code Reference,  Prev: PROVIDE_HIDDEN,  Up: Assignments

3.5.4 Source Code Reference
---------------------------

Accessing a linker script defined variable from source code is not
intuitive.  In particular a linker script symbol is not equivalent to a
variable declaration in a high level language, it is instead a symbol
that does not have a value.

   Before going further, it is important to note that compilers often
transform names in the source code into different names when they are
stored in the symbol table.  For example, Fortran compilers commonly
prepend or append an underscore, and C++ performs extensive `name
mangling'.  Therefore there might be a discrepancy between the name of
a variable as it is used in source code and the name of the same
variable as it is defined in a linker script.  For example in C a
linker script variable might be referred to as:

       extern int foo;

   But in the linker script it might be defined as:

       _foo = 1000;

   In the remaining examples however it is assumed that no name
transformation has taken place.

   When a symbol is declared in a high level language such as C, two
things happen.  The first is that the compiler reserves enough space in
the program's memory to hold the _value_ of the symbol.  The second is
that the compiler creates an entry in the program's symbol table which
holds the symbol's _address_.  ie the symbol table contains the address
of the block of memory holding the symbol's value.  So for example the
following C declaration, at file scope:

       int foo = 1000;

   creates a entry called `foo' in the symbol table.  This entry holds
the address of an `int' sized block of memory where the number 1000 is
initially stored.

   When a program references a symbol the compiler generates code that
first accesses the symbol table to find the address of the symbol's
memory block and then code to read the value from that memory block.
So:

       foo = 1;

   looks up the symbol `foo' in the symbol table, gets the address
associated with this symbol and then writes the value 1 into that
address.  Whereas:

       int * a = & foo;

   looks up the symbol `foo' in the symbol table, gets it address and
then copies this address into the block of memory associated with the
variable `a'.

   Linker scripts symbol declarations, by contrast, create an entry in
the symbol table but do not assign any memory to them.  Thus they are
an address without a value.  So for example the linker script
definition:

       foo = 1000;

   creates an entry in the symbol table called `foo' which holds the
address of memory location 1000, but nothing special is stored at
address 1000.  This means that you cannot access the _value_ of a
linker script defined symbol - it has no value - all you can do is
access the _address_ of a linker script defined symbol.

   Hence when you are using a linker script defined symbol in source
code you should always take the address of the symbol, and never
attempt to use its value.  For example suppose you want to copy the
contents of a section of memory called .ROM into a section called
.FLASH and the linker script contains these declarations:

       start_of_ROM   = .ROM;
       end_of_ROM     = .ROM + sizeof (.ROM) - 1;
       start_of_FLASH = .FLASH;

   Then the C source code to perform the copy would be:

       extern char start_of_ROM, end_of_ROM, start_of_FLASH;

       memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);

   Note the use of the `&' operators.  These are correct.


File: ld.info,  Node: SECTIONS,  Next: MEMORY,  Prev: Assignments,  Up: Scripts

3.6 SECTIONS Command
====================

The `SECTIONS' command tells the linker how to map input sections into
output sections, and how to place the output sections in memory.

   The format of the `SECTIONS' command is:
     SECTIONS
     {
       SECTIONS-COMMAND
       SECTIONS-COMMAND
       ...
     }

   Each SECTIONS-COMMAND may of be one of the following:

   * an `ENTRY' command (*note Entry command: Entry Point.)

   * a symbol assignment (*note Assignments::)

   * an output section description

   * an overlay description

   The `ENTRY' command and symbol assignments are permitted inside the
`SECTIONS' command for convenience in using the location counter in
those commands.  This can also make the linker script easier to
understand because you can use those commands at meaningful points in
the layout of the output file.

   Output section descriptions and overlay descriptions are described
below.

   If you do not use a `SECTIONS' command in your linker script, the
linker will place each input section into an identically named output
section in the order that the sections are first encountered in the
input files.  If all input sections are present in the first file, for
example, the order of sections in the output file will match the order
in the first input file.  The first section will be at address zero.

* Menu:

* Output Section Description::	Output section description
* Output Section Name::		Output section name
* Output Section Address::	Output section address
* Input Section::		Input section description
* Output Section Data::		Output section data
* Output Section Keywords::	Output section keywords
* Output Section Discarding::	Output section discarding
* Output Section Attributes::	Output section attributes
* Overlay Description::		Overlay description


File: ld.info,  Node: Output Section Description,  Next: Output Section Name,  Up: SECTIONS

3.6.1 Output Section Description
--------------------------------

The full description of an output section looks like this:
     SECTION [ADDRESS] [(TYPE)] :
       [AT(LMA)]
       [ALIGN(SECTION_ALIGN)]
       [SUBALIGN(SUBSECTION_ALIGN)]
       [CONSTRAINT]
       {
         OUTPUT-SECTION-COMMAND
         OUTPUT-SECTION-COMMAND
         ...
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]

   Most output sections do not use most of the optional section
attributes.

   The whitespace around SECTION is required, so that the section name
is unambiguous.  The colon and the curly braces are also required.  The
line breaks and other white space are optional.

   Each OUTPUT-SECTION-COMMAND may be one of the following:

   * a symbol assignment (*note Assignments::)

   * an input section description (*note Input Section::)

   * data values to include directly (*note Output Section Data::)

   * a special output section keyword (*note Output Section Keywords::)


File: ld.info,  Node: Output Section Name,  Next: Output Section Address,  Prev: Output Section Description,  Up: SECTIONS

3.6.2 Output Section Name
-------------------------

The name of the output section is SECTION.  SECTION must meet the
constraints of your output format.  In formats which only support a
limited number of sections, such as `a.out', the name must be one of
the names supported by the format (`a.out', for example, allows only
`.text', `.data' or `.bss'). If the output format supports any number
of sections, but with numbers and not names (as is the case for Oasys),
the name should be supplied as a quoted numeric string.  A section name
may consist of any sequence of characters, but a name which contains
any unusual characters such as commas must be quoted.

   The output section name `/DISCARD/' is special; *Note Output Section
Discarding::.


File: ld.info,  Node: Output Section Address,  Next: Input Section,  Prev: Output Section Name,  Up: SECTIONS

3.6.3 Output Section Address
----------------------------

The ADDRESS is an expression for the VMA (the virtual memory address)
of the output section.  This address is optional, but if it is provided
then the output address will be set exactly as specified.

   If the output address is not specified then one will be chosen for
the section, based on the heuristic below.  This address will be
adjusted to fit the alignment requirement of the output section.  The
alignment requirement is the strictest alignment of any input section
contained within the output section.

   The output section address heuristic is as follows:

   * If an output memory REGION is set for the section then it is added
     to this region and its address will be the next free address in
     that region.

   * If the MEMORY command has been used to create a list of memory
     regions then the first region which has attributes compatible with
     the section is selected to contain it.  The section's output
     address will be the next free address in that region; *Note
     MEMORY::.

   * If no memory regions were specified, or none match the section then
     the output address will be based on the current value of the
     location counter.

For example:

     .text . : { *(.text) }

and

     .text : { *(.text) }

are subtly different.  The first will set the address of the `.text'
output section to the current value of the location counter.  The
second will set it to the current value of the location counter aligned
to the strictest alignment of any of the `.text' input sections.

   The ADDRESS may be an arbitrary expression; *Note Expressions::.
For example, if you want to align the section on a 0x10 byte boundary,
so that the lowest four bits of the section address are zero, you could
do something like this:
     .text ALIGN(0x10) : { *(.text) }
   This works because `ALIGN' returns the current location counter
aligned upward to the specified value.

   Specifying ADDRESS for a section will change the value of the
location counter, provided that the section is non-empty.  (Empty
sections are ignored).


File: ld.info,  Node: Input Section,  Next: Output Section Data,  Prev: Output Section Address,  Up: SECTIONS

3.6.4 Input Section Description
-------------------------------

The most common output section command is an input section description.

   The input section description is the most basic linker script
operation.  You use output sections to tell the linker how to lay out
your program in memory.  You use input section descriptions to tell the
linker how to map the input files into your memory layout.

* Menu:

* Input Section Basics::	Input section basics
* Input Section Wildcards::	Input section wildcard patterns
* Input Section Common::	Input section for common symbols
* Input Section Keep::		Input section and garbage collection
* Input Section Example::	Input section example


File: ld.info,  Node: Input Section Basics,  Next: Input Section Wildcards,  Up: Input Section

3.6.4.1 Input Section Basics
............................

An input section description consists of a file name optionally followed
by a list of section names in parentheses.

   The file name and the section name may be wildcard patterns, which we
describe further below (*note Input Section Wildcards::).

   The most common input section description is to include all input
sections with a particular name in the output section.  For example, to
include all input `.text' sections, you would write:
     *(.text)
   Here the `*' is a wildcard which matches any file name.  To exclude
a list of files from matching the file name wildcard, EXCLUDE_FILE may
be used to match all files except the ones specified in the
EXCLUDE_FILE list.  For example:
     *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
   will cause all .ctors sections from all files except `crtend.o' and
`otherfile.o' to be included.

   There are two ways to include more than one section:
     *(.text .rdata)
     *(.text) *(.rdata)
   The difference between these is the order in which the `.text' and
`.rdata' input sections will appear in the output section.  In the
first example, they will be intermingled, appearing in the same order as
they are found in the linker input.  In the second example, all `.text'
input sections will appear first, followed by all `.rdata' input
sections.

   You can specify a file name to include sections from a particular
file.  You would do this if one or more of your files contain special
data that needs to be at a particular location in memory.  For example:
     data.o(.data)

   You can also specify files within archives by writing a pattern
matching the archive, a colon, then the pattern matching the file, with
no whitespace around the colon.

`archive:file'
     matches file within archive

`archive:'
     matches the whole archive

`:file'
     matches file but not one in an archive

   Either one or both of `archive' and `file' can contain shell
wildcards.  On DOS based file systems, the linker will assume that a
single letter followed by a colon is a drive specifier, so `c:myfile.o'
is a simple file specification, not `myfile.o' within an archive called
`c'.  `archive:file' filespecs may also be used within an
`EXCLUDE_FILE' list, but may not appear in other linker script
contexts.  For instance, you cannot extract a file from an archive by
using `archive:file' in an `INPUT' command.

   If you use a file name without a list of sections, then all sections
in the input file will be included in the output section.  This is not
commonly done, but it may by useful on occasion.  For example:
     data.o

   When you use a file name which is not an `archive:file' specifier
and does not contain any wild card characters, the linker will first
see if you also specified the file name on the linker command line or
in an `INPUT' command.  If you did not, the linker will attempt to open
the file as an input file, as though it appeared on the command line.
Note that this differs from an `INPUT' command, because the linker will
not search for the file in the archive search path.


File: ld.info,  Node: Input Section Wildcards,  Next: Input Section Common,  Prev: Input Section Basics,  Up: Input Section

3.6.4.2 Input Section Wildcard Patterns
.......................................

In an input section description, either the file name or the section
name or both may be wildcard patterns.

   The file name of `*' seen in many examples is a simple wildcard
pattern for the file name.

   The wildcard patterns are like those used by the Unix shell.

`*'
     matches any number of characters

`?'
     matches any single character

`[CHARS]'
     matches a single instance of any of the CHARS; the `-' character
     may be used to specify a range of characters, as in `[a-z]' to
     match any lower case letter

`\'
     quotes the following character

   When a file name is matched with a wildcard, the wildcard characters
will not match a `/' character (used to separate directory names on
Unix).  A pattern consisting of a single `*' character is an exception;
it will always match any file name, whether it contains a `/' or not.
In a section name, the wildcard characters will match a `/' character.

   File name wildcard patterns only match files which are explicitly
specified on the command line or in an `INPUT' command.  The linker
does not search directories to expand wildcards.

   If a file name matches more than one wildcard pattern, or if a file
name appears explicitly and is also matched by a wildcard pattern, the
linker will use the first match in the linker script.  For example, this
sequence of input section descriptions is probably in error, because the
`data.o' rule will not be used:
     .data : { *(.data) }
     .data1 : { data.o(.data) }

   Normally, the linker will place files and sections matched by
wildcards in the order in which they are seen during the link.  You can
change this by using the `SORT_BY_NAME' keyword, which appears before a
wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)').  When
the `SORT_BY_NAME' keyword is used, the linker will sort the files or
sections into ascending order by name before placing them in the output
file.

   `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
order by alignment before placing them in the output file.

   `SORT' is an alias for `SORT_BY_NAME'.

   When there are nested section sorting commands in linker script,
there can be at most 1 level of nesting for section sorting commands.

  1. `SORT_BY_NAME' (`SORT_BY_ALIGNMENT' (wildcard section pattern)).
     It will sort the input sections by name first, then by alignment
     if 2 sections have the same name.

  2. `SORT_BY_ALIGNMENT' (`SORT_BY_NAME' (wildcard section pattern)).
     It will sort the input sections by alignment first, then by name
     if 2 sections have the same alignment.

  3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
     treated the same as `SORT_BY_NAME' (wildcard section pattern).

  4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
     pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
     section pattern).

  5. All other nested section sorting commands are invalid.

   When both command line section sorting option and linker script
section sorting command are used, section sorting command always takes
precedence over the command line option.

   If the section sorting command in linker script isn't nested, the
command line option will make the section sorting command to be treated
as nested sorting command.

  1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
     alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
     (wildcard section pattern)).

  2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
     `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
     (`SORT_BY_NAME' (wildcard section pattern)).

   If the section sorting command in linker script is nested, the
command line option will be ignored.

   If you ever get confused about where input sections are going, use
the `-M' linker option to generate a map file.  The map file shows
precisely how input sections are mapped to output sections.

   This example shows how wildcard patterns might be used to partition
files.  This linker script directs the linker to place all `.text'
sections in `.text' and all `.bss' sections in `.bss'.  The linker will
place the `.data' section from all files beginning with an upper case
character in `.DATA'; for all other files, the linker will place the
`.data' section in `.data'.
     SECTIONS {
       .text : { *(.text) }
       .DATA : { [A-Z]*(.data) }
       .data : { *(.data) }
       .bss : { *(.bss) }
     }


File: ld.info,  Node: Input Section Common,  Next: Input Section Keep,  Prev: Input Section Wildcards,  Up: Input Section

3.6.4.3 Input Section for Common Symbols
........................................

A special notation is needed for common symbols, because in many object
file formats common symbols do not have a particular input section.  The
linker treats common symbols as though they are in an input section
named `COMMON'.

   You may use file names with the `COMMON' section just as with any
other input sections.  You can use this to place common symbols from a
particular input file in one section while common symbols from other
input files are placed in another section.

   In most cases, common symbols in input files will be placed in the
`.bss' section in the output file.  For example:
     .bss { *(.bss) *(COMMON) }

   Some object file formats have more than one type of common symbol.
For example, the MIPS ELF object file format distinguishes standard
common symbols and small common symbols.  In this case, the linker will
use a different special section name for other types of common symbols.
In the case of MIPS ELF, the linker uses `COMMON' for standard common
symbols and `.scommon' for small common symbols.  This permits you to
map the different types of common symbols into memory at different
locations.

   You will sometimes see `[COMMON]' in old linker scripts.  This
notation is now considered obsolete.  It is equivalent to `*(COMMON)'.


File: ld.info,  Node: Input Section Keep,  Next: Input Section Example,  Prev: Input Section Common,  Up: Input Section

3.6.4.4 Input Section and Garbage Collection
............................................

When link-time garbage collection is in use (`--gc-sections'), it is
often useful to mark sections that should not be eliminated.  This is
accomplished by surrounding an input section's wildcard entry with
`KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.


File: ld.info,  Node: Input Section Example,  Prev: Input Section Keep,  Up: Input Section

3.6.4.5 Input Section Example
.............................

The following example is a complete linker script.  It tells the linker
to read all of the sections from file `all.o' and place them at the
start of output section `outputa' which starts at location `0x10000'.
All of section `.input1' from file `foo.o' follows immediately, in the
same output section.  All of section `.input2' from `foo.o' goes into
output section `outputb', followed by section `.input1' from `foo1.o'.
All of the remaining `.input1' and `.input2' sections from any files
are written to output section `outputc'.

     SECTIONS {
       outputa 0x10000 :
         {
         all.o
         foo.o (.input1)
         }
       outputb :
         {
         foo.o (.input2)
         foo1.o (.input1)
         }
       outputc :
         {
         *(.input1)
         *(.input2)
         }
     }


File: ld.info,  Node: Output Section Data,  Next: Output Section Keywords,  Prev: Input Section,  Up: SECTIONS

3.6.5 Output Section Data
-------------------------

You can include explicit bytes of data in an output section by using
`BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
command.  Each keyword is followed by an expression in parentheses
providing the value to store (*note Expressions::).  The value of the
expression is stored at the current value of the location counter.

   The `BYTE', `SHORT', `LONG', and `QUAD' commands store one, two,
four, and eight bytes (respectively).  After storing the bytes, the
location counter is incremented by the number of bytes stored.

   For example, this will store the byte 1 followed by the four byte
value of the symbol `addr':
     BYTE(1)
     LONG(addr)

   When using a 64 bit host or target, `QUAD' and `SQUAD' are the same;
they both store an 8 byte, or 64 bit, value.  When both host and target
are 32 bits, an expression is computed as 32 bits.  In this case `QUAD'
stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
bit value sign extended to 64 bits.

   If the object file format of the output file has an explicit
endianness, which is the normal case, the value will be stored in that
endianness.  When the object file format does not have an explicit
endianness, as is true of, for example, S-records, the value will be
stored in the endianness of the first input object file.

   Note--these commands only work inside a section description and not
between them, so the following will produce an error from the linker:
     SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
   whereas this will work:
     SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }

   You may use the `FILL' command to set the fill pattern for the
current section.  It is followed by an expression in parentheses.  Any
otherwise unspecified regions of memory within the section (for example,
gaps left due to the required alignment of input sections) are filled
with the value of the expression, repeated as necessary.  A `FILL'
statement covers memory locations after the point at which it occurs in
the section definition; by including more than one `FILL' statement,
you can have different fill patterns in different parts of an output
section.

   This example shows how to fill unspecified regions of memory with the
value `0x90':
     FILL(0x90909090)

   The `FILL' command is similar to the `=FILLEXP' output section
attribute, but it only affects the part of the section following the
`FILL' command, rather than the entire section.  If both are used, the
`FILL' command takes precedence.  *Note Output Section Fill::, for
details on the fill expression.


File: ld.info,  Node: Output Section Keywords,  Next: Output Section Discarding,  Prev: Output Section Data,  Up: SECTIONS

3.6.6 Output Section Keywords
-----------------------------

There are a couple of keywords which can appear as output section
commands.

`CREATE_OBJECT_SYMBOLS'
     The command tells the linker to create a symbol for each input
     file.  The name of each symbol will be the name of the
     corresponding input file.  The section of each symbol will be the
     output section in which the `CREATE_OBJECT_SYMBOLS' command
     appears.

     This is conventional for the a.out object file format.  It is not
     normally used for any other object file format.

`CONSTRUCTORS'
     When linking using the a.out object file format, the linker uses an
     unusual set construct to support C++ global constructors and
     destructors.  When linking object file formats which do not support
     arbitrary sections, such as ECOFF and XCOFF, the linker will
     automatically recognize C++ global constructors and destructors by
     name.  For these object file formats, the `CONSTRUCTORS' command
     tells the linker to place constructor information in the output
     section where the `CONSTRUCTORS' command appears.  The
     `CONSTRUCTORS' command is ignored for other object file formats.

     The symbol `__CTOR_LIST__' marks the start of the global
     constructors, and the symbol `__CTOR_END__' marks the end.
     Similarly, `__DTOR_LIST__' and `__DTOR_END__' mark the start and
     end of the global destructors.  The first word in the list is the
     number of entries, followed by the address of each constructor or
     destructor, followed by a zero word.  The compiler must arrange to
     actually run the code.  For these object file formats GNU C++
     normally calls constructors from a subroutine `__main'; a call to
     `__main' is automatically inserted into the startup code for
     `main'.  GNU C++ normally runs destructors either by using
     `atexit', or directly from the function `exit'.

     For object file formats such as `COFF' or `ELF' which support
     arbitrary section names, GNU C++ will normally arrange to put the
     addresses of global constructors and destructors into the `.ctors'
     and `.dtors' sections.  Placing the following sequence into your
     linker script will build the sort of table which the GNU C++
     runtime code expects to see.

                __CTOR_LIST__ = .;
                LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
                *(.ctors)
                LONG(0)
                __CTOR_END__ = .;
                __DTOR_LIST__ = .;
                LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
                *(.dtors)
                LONG(0)
                __DTOR_END__ = .;

     If you are using the GNU C++ support for initialization priority,
     which provides some control over the order in which global
     constructors are run, you must sort the constructors at link time
     to ensure that they are executed in the correct order.  When using
     the `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
     instead.  When using the `.ctors' and `.dtors' sections, use
     `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
     just `*(.ctors)' and `*(.dtors)'.

     Normally the compiler and linker will handle these issues
     automatically, and you will not need to concern yourself with
     them.  However, you may need to consider this if you are using C++
     and writing your own linker scripts.



File: ld.info,  Node: Output Section Discarding,  Next: Output Section Attributes,  Prev: Output Section Keywords,  Up: SECTIONS

3.6.7 Output Section Discarding
-------------------------------

The linker will not create output sections with no contents.  This is
for convenience when referring to input sections that may or may not be
present in any of the input files.  For example:
     .foo : { *(.foo) }
   will only create a `.foo' section in the output file if there is a
`.foo' section in at least one input file, and if the input sections
are not all empty.  Other link script directives that allocate space in
an output section will also create the output section.

   The linker will ignore address assignments (*note Output Section
Address::) on discarded output sections, except when the linker script
defines symbols in the output section.  In that case the linker will
obey the address assignments, possibly advancing dot even though the
section is discarded.

   The special output section name `/DISCARD/' may be used to discard
input sections.  Any input sections which are assigned to an output
section named `/DISCARD/' are not included in the output file.


File: ld.info,  Node: Output Section Attributes,  Next: Overlay Description,  Prev: Output Section Discarding,  Up: SECTIONS

3.6.8 Output Section Attributes
-------------------------------

We showed above that the full description of an output section looked
like this:

     SECTION [ADDRESS] [(TYPE)] :
       [AT(LMA)]
       [ALIGN(SECTION_ALIGN)]
       [SUBALIGN(SUBSECTION_ALIGN)]
       [CONSTRAINT]
       {
         OUTPUT-SECTION-COMMAND
         OUTPUT-SECTION-COMMAND
         ...
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]

   We've already described SECTION, ADDRESS, and
OUTPUT-SECTION-COMMAND.  In this section we will describe the remaining
section attributes.

* Menu:

* Output Section Type::		Output section type
* Output Section LMA::		Output section LMA
* Forced Output Alignment::	Forced Output Alignment
* Forced Input Alignment::	Forced Input Alignment
* Output Section Constraint::   Output section constraint
* Output Section Region::	Output section region
* Output Section Phdr::		Output section phdr
* Output Section Fill::		Output section fill


File: ld.info,  Node: Output Section Type,  Next: Output Section LMA,  Up: Output Section Attributes

3.6.8.1 Output Section Type
...........................

Each output section may have a type.  The type is a keyword in
parentheses.  The following types are defined:

`NOLOAD'
     The section should be marked as not loadable, so that it will not
     be loaded into memory when the program is run.

`DSECT'
`COPY'
`INFO'
`OVERLAY'
     These type names are supported for backward compatibility, and are
     rarely used.  They all have the same effect: the section should be
     marked as not allocatable, so that no memory is allocated for the
     section when the program is run.

   The linker normally sets the attributes of an output section based on
the input sections which map into it.  You can override this by using
the section type.  For example, in the script sample below, the `ROM'
section is addressed at memory location `0' and does not need to be
loaded when the program is run.
     SECTIONS {
       ROM 0 (NOLOAD) : { ... }
       ...
     }


File: ld.info,  Node: Output Section LMA,  Next: Forced Output Alignment,  Prev: Output Section Type,  Up: Output Section Attributes

3.6.8.2 Output Section LMA
..........................

Every section has a virtual address (VMA) and a load address (LMA); see
*Note Basic Script Concepts::.  The virtual address is specified by the
*note Output Section Address:: described earlier.  The load address is
specified by the `AT' or `AT>' keywords.  Specifying a load address is
optional.

   The `AT' keyword takes an expression as an argument.  This specifies
the exact load address of the section.  The `AT>' keyword takes the
name of a memory region as an argument.  *Note MEMORY::.  The load
address of the section is set to the next free address in the region,
aligned to the section's alignment requirements.

   If neither `AT' nor `AT>' is specified for an allocatable section,
the linker will use the following heuristic to determine the load
address:

   * If the section has a specific VMA address, then this is used as
     the LMA address as well.

   * If the section is not allocatable then its LMA is set to its VMA.

   * Otherwise if a memory region can be found that is compatible with
     the current section, and this region contains at least one
     section, then the LMA is set so the difference between the VMA and
     LMA is the same as the difference between the VMA and LMA of the
     last section in the located region.

   * If no memory regions have been declared then a default region that
     covers the entire address space is used in the previous step.

   * If no suitable region could be found, or there was no previous
     section then the LMA is set equal to the VMA.

   This feature is designed to make it easy to build a ROM image.  For
example, the following linker script creates three output sections: one
called `.text', which starts at `0x1000', one called `.mdata', which is
loaded at the end of the `.text' section even though its VMA is
`0x2000', and one called `.bss' to hold uninitialized data at address
`0x3000'.  The symbol `_data' is defined with the value `0x2000', which
shows that the location counter holds the VMA value, not the LMA value.

     SECTIONS
       {
       .text 0x1000 : { *(.text) _etext = . ; }
       .mdata 0x2000 :
         AT ( ADDR (.text) + SIZEOF (.text) )
         { _data = . ; *(.data); _edata = . ;  }
       .bss 0x3000 :
         { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
     }

   The run-time initialization code for use with a program generated
with this linker script would include something like the following, to
copy the initialized data from the ROM image to its runtime address.
Notice how this code takes advantage of the symbols defined by the
linker script.

     extern char _etext, _data, _edata, _bstart, _bend;
     char *src = &_etext;
     char *dst = &_data;

     /* ROM has data at end of text; copy it.  */
     while (dst < &_edata)
       *dst++ = *src++;

     /* Zero bss.  */
     for (dst = &_bstart; dst< &_bend; dst++)
       *dst = 0;


File: ld.info,  Node: Forced Output Alignment,  Next: Forced Input Alignment,  Prev: Output Section LMA,  Up: Output Section Attributes

3.6.8.3 Forced Output Alignment
...............................

You can increase an output section's alignment by using ALIGN.


File: ld.info,  Node: Forced Input Alignment,  Next: Output Section Constraint,  Prev: Forced Output Alignment,  Up: Output Section Attributes

3.6.8.4 Forced Input Alignment
..............................

You can force input section alignment within an output section by using
SUBALIGN.  The value specified overrides any alignment given by input
sections, whether larger or smaller.


File: ld.info,  Node: Output Section Constraint,  Next: Output Section Region,  Prev: Forced Input Alignment,  Up: Output Section Attributes

3.6.8.5 Output Section Constraint
.................................

You can specify that an output section should only be created if all of
its input sections are read-only or all of its input sections are
read-write by using the keyword `ONLY_IF_RO' and `ONLY_IF_RW'
respectively.


File: ld.info,  Node: Output Section Region,  Next: Output Section Phdr,  Prev: Output Section Constraint,  Up: Output Section Attributes

3.6.8.6 Output Section Region
.............................

You can assign a section to a previously defined region of memory by
using `>REGION'.  *Note MEMORY::.

   Here is a simple example:
     MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
     SECTIONS { ROM : { *(.text) } >rom }


File: ld.info,  Node: Output Section Phdr,  Next: Output Section Fill,  Prev: Output Section Region,  Up: Output Section Attributes

3.6.8.7 Output Section Phdr
...........................

You can assign a section to a previously defined program segment by
using `:PHDR'.  *Note PHDRS::.  If a section is assigned to one or more
segments, then all subsequent allocated sections will be assigned to
those segments as well, unless they use an explicitly `:PHDR' modifier.
You can use `:NONE' to tell the linker to not put the section in any
segment at all.

   Here is a simple example:
     PHDRS { text PT_LOAD ; }
     SECTIONS { .text : { *(.text) } :text }


File: ld.info,  Node: Output Section Fill,  Prev: Output Section Phdr,  Up: Output Section Attributes

3.6.8.8 Output Section Fill
...........................

You can set the fill pattern for an entire section by using `=FILLEXP'.
FILLEXP is an expression (*note Expressions::).  Any otherwise
unspecified regions of memory within the output section (for example,
gaps left due to the required alignment of input sections) will be
filled with the value, repeated as necessary.  If the fill expression
is a simple hex number, ie. a string of hex digit starting with `0x'
and without a trailing `k' or `M', then an arbitrarily long sequence of
hex digits can be used to specify the fill pattern;  Leading zeros
become part of the pattern too.  For all other cases, including extra
parentheses or a unary `+', the fill pattern is the four least
significant bytes of the value of the expression.  In all cases, the
number is big-endian.

   You can also change the fill value with a `FILL' command in the
output section commands; (*note Output Section Data::).

   Here is a simple example:
     SECTIONS { .text : { *(.text) } =0x90909090 }


File: ld.info,  Node: Overlay Description,  Prev: Output Section Attributes,  Up: SECTIONS

3.6.9 Overlay Description
-------------------------

An overlay description provides an easy way to describe sections which
are to be loaded as part of a single memory image but are to be run at
the same memory address.  At run time, some sort of overlay manager will
copy the overlaid sections in and out of the runtime memory address as
required, perhaps by simply manipulating addressing bits.  This approach
can be useful, for example, when a certain region of memory is faster
than another.

   Overlays are described using the `OVERLAY' command.  The `OVERLAY'
command is used within a `SECTIONS' command, like an output section
description.  The full syntax of the `OVERLAY' command is as follows:
     OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
       {
         SECNAME1
           {
             OUTPUT-SECTION-COMMAND
             OUTPUT-SECTION-COMMAND
             ...
           } [:PHDR...] [=FILL]
         SECNAME2
           {
             OUTPUT-SECTION-COMMAND
             OUTPUT-SECTION-COMMAND
             ...
           } [:PHDR...] [=FILL]
         ...
       } [>REGION] [:PHDR...] [=FILL]

   Everything is optional except `OVERLAY' (a keyword), and each
section must have a name (SECNAME1 and SECNAME2 above).  The section
definitions within the `OVERLAY' construct are identical to those
within the general `SECTIONS' contruct (*note SECTIONS::), except that
no addresses and no memory regions may be defined for sections within
an `OVERLAY'.

   The sections are all defined with the same starting address.  The
load addresses of the sections are arranged such that they are
consecutive in memory starting at the load address used for the
`OVERLAY' as a whole (as with normal section definitions, the load
address is optional, and defaults to the start address; the start
address is also optional, and defaults to the current value of the
location counter).

   If the `NOCROSSREFS' keyword is used, and there any references among
the sections, the linker will report an error.  Since the sections all
run at the same address, it normally does not make sense for one
section to refer directly to another.  *Note NOCROSSREFS: Miscellaneous
Commands.

   For each section within the `OVERLAY', the linker automatically
provides two symbols.  The symbol `__load_start_SECNAME' is defined as
the starting load address of the section.  The symbol
`__load_stop_SECNAME' is defined as the final load address of the
section.  Any characters within SECNAME which are not legal within C
identifiers are removed.  C (or assembler) code may use these symbols
to move the overlaid sections around as necessary.

   At the end of the overlay, the value of the location counter is set
to the start address of the overlay plus the size of the largest
section.

   Here is an example.  Remember that this would appear inside a
`SECTIONS' construct.
       OVERLAY 0x1000 : AT (0x4000)
        {
          .text0 { o1/*.o(.text) }
          .text1 { o2/*.o(.text) }
        }
This will define both `.text0' and `.text1' to start at address
0x1000.  `.text0' will be loaded at address 0x4000, and `.text1' will
be loaded immediately after `.text0'.  The following symbols will be
defined if referenced: `__load_start_text0', `__load_stop_text0',
`__load_start_text1', `__load_stop_text1'.

   C code to copy overlay `.text1' into the overlay area might look
like the following.

       extern char __load_start_text1, __load_stop_text1;
       memcpy ((char *) 0x1000, &__load_start_text1,
               &__load_stop_text1 - &__load_start_text1);

   Note that the `OVERLAY' command is just syntactic sugar, since
everything it does can be done using the more basic commands.  The above
example could have been written identically as follows.

       .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
       PROVIDE (__load_start_text0 = LOADADDR (.text0));
       PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
       .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
       PROVIDE (__load_start_text1 = LOADADDR (.text1));
       PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
       . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));


File: ld.info,  Node: MEMORY,  Next: PHDRS,  Prev: SECTIONS,  Up: Scripts

3.7 MEMORY Command
==================

The linker's default configuration permits allocation of all available
memory.  You can override this by using the `MEMORY' command.

   The `MEMORY' command describes the location and size of blocks of
memory in the target.  You can use it to describe which memory regions
may be used by the linker, and which memory regions it must avoid.  You
can then assign sections to particular memory regions.  The linker will
set section addresses based on the memory regions, and will warn about
regions that become too full.  The linker will not shuffle sections
around to fit into the available regions.

   A linker script may contain at most one use of the `MEMORY' command.
However, you can define as many blocks of memory within it as you
wish.  The syntax is:
     MEMORY
       {
         NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
         ...
       }

   The NAME is a name used in the linker script to refer to the region.
The region name has no meaning outside of the linker script.  Region
names are stored in a separate name space, and will not conflict with
symbol names, file names, or section names.  Each memory region must
have a distinct name within the `MEMORY' command.  However you can add
later alias names to existing memory regions with the *Note
REGION_ALIAS:: command.

   The ATTR string is an optional list of attributes that specify
whether to use a particular memory region for an input section which is
not explicitly mapped in the linker script.  As described in *Note
SECTIONS::, if you do not specify an output section for some input
section, the linker will create an output section with the same name as
the input section.  If you define region attributes, the linker will use
them to select the memory region for the output section that it creates.

   The ATTR string must consist only of the following characters:
`R'
     Read-only section

`W'
     Read/write section

`X'
     Executable section

`A'
     Allocatable section

`I'
     Initialized section

`L'
     Same as `I'

`!'
     Invert the sense of any of the attributes that follow

   If a unmapped section matches any of the listed attributes other than
`!', it will be placed in the memory region.  The `!' attribute
reverses this test, so that an unmapped section will be placed in the
memory region only if it does not match any of the listed attributes.

   The ORIGIN is an numerical expression for the start address of the
memory region.  The expression must evaluate to a constant and it
cannot involve any symbols.  The keyword `ORIGIN' may be abbreviated to
`org' or `o' (but not, for example, `ORG').

   The LEN is an expression for the size in bytes of the memory region.
As with the ORIGIN expression, the expression must be numerical only
and must evaluate to a constant.  The keyword `LENGTH' may be
abbreviated to `len' or `l'.

   In the following example, we specify that there are two memory
regions available for allocation: one starting at `0' for 256 kilobytes,
and the other starting at `0x40000000' for four megabytes.  The linker
will place into the `rom' memory region every section which is not
explicitly mapped into a memory region, and is either read-only or
executable.  The linker will place other sections which are not
explicitly mapped into a memory region into the `ram' memory region.

     MEMORY
       {
         rom (rx)  : ORIGIN = 0, LENGTH = 256K
         ram (!rx) : org = 0x40000000, l = 4M
       }

   Once you define a memory region, you can direct the linker to place
specific output sections into that memory region by using the `>REGION'
output section attribute.  For example, if you have a memory region
named `mem', you would use `>mem' in the output section definition.
*Note Output Section Region::.  If no address was specified for the
output section, the linker will set the address to the next available
address within the memory region.  If the combined output sections
directed to a memory region are too large for the region, the linker
will issue an error message.

   It is possible to access the origin and length of a memory in an
expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:

       _fstack = ORIGIN(ram) + LENGTH(ram) - 4;


File: ld.info,  Node: PHDRS,  Next: VERSION,  Prev: MEMORY,  Up: Scripts

3.8 PHDRS Command
=================

The ELF object file format uses "program headers", also knows as
"segments".  The program headers describe how the program should be
loaded into memory.  You can print them out by using the `objdump'
program with the `-p' option.

   When you run an ELF program on a native ELF system, the system loader
reads the program headers in order to figure out how to load the
program.  This will only work if the program headers are set correctly.
This manual does not describe the details of how the system loader
interprets program headers; for more information, see the ELF ABI.

   The linker will create reasonable program headers by default.
However, in some cases, you may need to specify the program headers more
precisely.  You may use the `PHDRS' command for this purpose.  When the
linker sees the `PHDRS' command in the linker script, it will not
create any program headers other than the ones specified.

   The linker only pays attention to the `PHDRS' command when
generating an ELF output file.