Syntax of an input section description

ARM Compiler toolchain v5.02 for µVision Linker Reference

Home > Formal syntax of the scatter file > Syntax of an input section description

Syntax of an input section description

The syntax of an input section description, in Backus-Naur Form (BNF), is:

input_section_description ::= 

  module_select_pattern 
        [ "(" input_section_selector ( "," input_section_selector )* ")" ]  input_section_selector ::= 

        ("+" input_section_attr | input_section_pattern | input_symbol_pattern | section_properties)

where:

module_select_pattern

A pattern constructed from literal text. The wildcard character * matches zero or more characters and ? matches any single character.

Matching is not case-sensitive, even on hosts with case-sensitive file naming.

Use *.o to match all objects. Use * to match all object files and libraries.

You can use quoted filenames, for example "file one.o".

An input section matches a module selector pattern when module_select_pattern matches one of the following:

The name of the object file containing the section.
The name of the library member (without leading path name).
The full name of the library (including path name) the section is extracted from. If the names contain spaces, use wild characters to simplify searching. For example, use *libname.lib to match C:\lib dir\libname.lib.

The following module selector patterns describe the placement order of an input section within the execution region:

.ANY module selector for unassigned sections: The special module selector pattern .ANY enables you to assign input sections to execution regions without considering their parent module. Use .ANY to fill up the execution regions with input sections that do not have to be placed at specific locations.
Modified selectors: You cannot have two * selectors in a scatter file. You can, however, use two modified selectors, for example *A and *B, and you can use a .ANY selector together with a * module selector. The * module selector has higher precedence than .ANY. If the portion of the file containing the * selector is removed, the .ANY selector then becomes active.

Note

Only input sections that match both module_select_pattern and at least one input_section_attr or input_section_pattern are included in the execution region.
If you omit (+ input_section_attr) and (input_section_pattern), the default is +RO.
Do not rely on input section names generated by the compiler, or used by ARM library code. These can change between compilations if, for example, different compiler options are used. In addition, section naming conventions used by the compiler are not guaranteed to remain constant between releases.

input_section_attr

An attribute selector matched against the input section attributes. Each input_section_attr follows a +.

If you are specifying a pattern to match the input section name, the name must be preceded by a +. You can omit any comma immediately followed by a +.

The selectors are not case-sensitive. The following selectors are recognized:

RO-CODE
RO-DATA
RO, selects both RO-CODE and RO-DATA
RW-DATA
RW-CODE
RW, selects both RW-CODE and RW-DATA
ZI
ENTRY, that is, a section containing an ENTRY point.

The following synonyms are recognized:

CODE for RO-CODE
CONST for RO-DATA
TEXT for RO
DATA for RW
BSS for ZI.

The following pseudo-attributes are recognized:

FIRST
LAST.

Use FIRST and LAST to mark the first and last sections in an execution region if the placement order is important. For example, if a specific input section must be first in the region and an input section containing a checksum must be last.

There can be only one FIRST or one LAST attribute for an execution region, and it must follow a single input_section_attr. For example:

*(section, +FIRST): This pattern is correct.
*(+FIRST, section): This pattern is incorrect and produces an error message.

input_section_pattern

A pattern that is matched, without case sensitivity, against the input section name. It is constructed from literal text. The wildcard character * matches 0 or more characters, and ? matches any single character.

You can use a quoted input section name.

Note

If you use more than one input_section_pattern, ensure that there are no duplicate patterns in different execution regions to avoid ambiguity errors.

input_symbol_pattern

You can select the input section by the name of a global symbol that the section defines. This enables you to choose individual sections with the same name from partially linked objects.

The :gdef: prefix distinguishes a global symbol pattern from a section pattern. For example, use :gdef:mysym to select the section that defines mysym. The following example shows a scatter file in which ExecReg1 contains the section that defines global symbol mysym1, and the section that contains global symbol mysym2:

LoadRegion 0x8000
{
    ExecReg1 +0
    {
        *(:gdef:mysym1)
        *(:gdef:mysym2)
    }
                        ; rest of scatter-loading description
}

You can use a quoted global symbol pattern. The :gdef: prefix can be inside or outside the quotes.

Note

If you use more than one input_symbol_pattern, ensure that there are no duplicate patterns in different execution regions to avoid ambiguity errors.

The order of input section descriptors is not significant.

section_properties

A section property can be +FIRST, +LAST, and OVERALIGN value.

The value for OVERALIGN must be a positive power of 2 and must be greater than or equal to 4.

Note

The BNF definitions contain additional line returns and spaces to improve readability. They are not required in the scatter-loading definition and are ignored if present in the file.

Examples of module select patterns

Examples of module_select_pattern specifications are:

* matches any module or library
*.o matches any object module
math.o matches the math.o module
*armlib* matches all C libraries supplied by ARM
"file 1.o" matches the file file 1.o
*math.lib matches any library path ending with math.lib. For example, C:\apps\lib\math\satmath.lib.

Examples of input section selector patterns

Examples of input_section_selector specifications are:

+RO is an input section attribute that matches all RO code and all RO data
+RW,+ZI is an input section attribute that matches all RW code, all RW data, and all ZI data
BLOCK_42 is an input section pattern that matches sections named BLOCK_42. There can be multiple ELF sections with the same BLOCK_42 name that possess different attributes, for example +RO-CODE,+RW.

Syntax of an input section description