11.4. Specifying Output Sections

11.4.1. Section Definitions

The most frequently used statement in the SECTIONS command is the section definition, which specifies the properties of an output section: its location, alignment, contents, fill pattern, and target memory region. Most of these specifications are optional; the simplest form of a section definition is

SECTIONS { ...
  secname : {
    contents
  }
... }

secname is the name of the output section, and contents a specification of what goes there—for example, a list of input files or sections of input files (see Section 11.4.2). As you might assume, the white-space shown is optional. You do need the colon ":" and the braces "{}", however.

secname must meet the constraints of your output format. In formats that 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 any name that does not conform to the standard linker symbol name syntax must be quoted. See Section 6.3, Symbols.

The special secname "/DISCARD/" may be used to discard input sections. Any sections that are assigned to an output section named "/DISCARD/" are not included in the final link output.

The linker will not create output sections that do not have any contents. This is for convenience when referring to input sections that may or may not exist. 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.

11.4.2. Section Placement

In a section definition, you can specify the contents of an output section by listing particular input files, by listing particular input-file sections, or by a combination of the two. You can also place arbitrary data in the section, and define symbols relative to the beginning of the section.

The contents of a section definition may include any of the following kinds of statement. You can include as many of these as you like in a single section definition, separated from one another by white-space.

In any place where you may use a specific file or section name, you may also use a wild-card pattern. The linker handles wild-cards much as the UNIX shell does. A "*" character matches any number of characters. A "?" character matches any single character. The sequence "[chars]" will match 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. A "\" character may be used to quote the following character.

When a file name is matched with a wild-card, the wild-card 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. In a section name, the wild-card characters will match a "/" character.

Wild-cards only match files that are explicitly specified on the command line. The linker does not search directories to expand wild-cards. However, if you specify a simple file name—a name with no wild-card characters—in a linker script, and the file name is not also specified on the command line, the linker will attempt to open the file as though it appeared on the command line.

In the following example, the command script arranges the output file into three consecutive sections, named .text, .data, and .bss, taking the input for each from the correspondingly named sections of all the input files:

SECTIONS {
  .text : { *(.text) }
  .data : { *(.data) }
  .bss :  { *(.bss)  *(COMMON) }
}

The following example reads all of the sections from file all.o and places 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)
    }
}

This example shows how wild-card patterns might be used to partition files. All .text sections are placed in .text, and all .bss sections are placed in .bss. For all files beginning with an upper case character, the .data section is placed into .DATA; for all other files, the .data section is placed into .data.

SECTIONS {
  .text : { *(.text) }
  .DATA : { [A-Z]*(.data) }
  .data : { *(.data) }
  .bss : { *(.bss) }
}

11.4.3. Section Data Expressions

The foregoing statements arrange, in your output file, data originating from your input files. You can also place data directly in an output section from the link command script. Most of these additional statements involve expressions (see Expressions, Section 11.2). Although these statements are shown separately here for ease of presentation, no such segregation is needed within a section definition in the SECTIONS command; you can intermix them freely with any of the statements we've just described.

11.4.4. Optional Section Attributes

Here is the full syntax of a section definition, including all the optional portions:

SECTIONS {
...
secname start BLOCK(align) (NOLOAD) : AT ( ldadr )
  { contents } >region :phdr =fill
...
}

secname and contents are required. See Section 11.4.1, and Section 11.4.2, for details on contents. The remaining elements—start, BLOCK(align), (NOLOAD), AT ( ldadr ), >region, :phdr, and =fill—are all optional.

11.4.5. Overlays

The OVERLAY command provides an easy way to describe sections that 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.

The OVERLAY command is used within a SECTIONS command. It appears as follows:

  OVERLAY start : [ NOCROSSREFS ] AT ( ldaddr )
   {
     secname1 { contents } :phdr =fill
     secname2 { contents } :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 construct (see Section 11.4), 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 .).

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. See Section 11.7.

For each section within the OVERLAY, the linker automatically defines 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 that 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 . 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: __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) }
  __load_start_text0 = LOADADDR (.text0);
  __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
  .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
  __load_start_text1 = LOADADDR (.text1);
  __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
  . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));