Input section description

RealView^® Compilation Tools for µVision Linker and Utilities Guide

Version 3.1

Home > Using Scatter-loading Description Files > Formal syntax of the scatter-loading description file > Input section description

5.2.5. Input section description

An input section description is a pattern that identifies input sections by:

Module name (object filename, library member name, or library filename). The module name can use wildcard characters.
Input section name, or input section attributes such as READ-ONLY, or CODE.
Symbol name.

Figure 5.8 shows the components of a typical input section description.

Figure 5.8. Components of an input section description

The syntax, in 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)

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 case-insensitive, even on hosts with case-sensitive file naming.

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

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 wildcards to simplify searching. For example, use *libname.lib to match C:\lib dir\libname.lib.

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 do not care assignments.

Use .ANYnum to give a specific priority ordering where num is a positive integer suffix from 0 upwards. The highest priority being given to the highest integer.

Example 5.1. .ANY with an integer suffix

lr1 0x8000 1024
{
    er1 +0 512
    {
        .ANY1(+RO) ; evenly distributed with er3
    }
    er2 +0 256
    {
        .ANY2(+RO) ; Highest priority, so filled first
    }
    er3 +0 256
    {
        .ANY1(+RO) ; evenly distributed with er1
    }
}

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.

The following attribute selector patterns describe the placement order of a section within the execution region:

First and last sections

FIRST and LAST can be used 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 only be one FIRST or LAST attribute in an input_section_selector list and it must follow a single input_section_attr. For example:

*(section, +FIRST): This is pattern is correct
*(+FIRST, section): This pattern is incorrect and produces an error message: Error: L6234E: FIRST must follow a single selector.

Special module selector

The special module selector pattern .ANY enables you to assign input sections to execution regions without considering their parent module. Use one or more .ANY patterns to fill up the execution regions with do not care assignments. In most cases, using a single .ANY is equivalent to using the * module selector.

Modified selectors

You cannot have two * selectors in a scatter-loading description 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.

Unassigned sections

The input section descriptions having the .ANY module selector pattern are resolved after all other (non-.ANY) input section descriptions have been resolved. All sections not assigned to an execution region are assigned to a .ANY region.If more than one .ANY pattern is present, the linker takes the section with the largest size not assigned to an execution region and assigns the section to the most specific .ANY execution region that has enough free space. When armlink makes this choice, .ANY(.text) is judged to be more specific than .ANY(+RO).

If several execution regions are equally specific then the section is assigned to the execution region with the most available remaining space.

For example:

If you have two equally specific execution regions where one has a size limit of 0x2000 and the other has no limit, then all the sections are assigned to the second unbounded .ANY region.
If you have two equally specific execution regions where one has a size limit of 0x2000 and the other has a size limit of 0x3000, then the first sections to be placed are assigned to the second .ANY region of size limit 0x3000 until the remaining size of the second .ANY is reduced to 0x2000. From this point, sections are assigned alternately between both .ANY execution regions.

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.

Note

If you use more than one input_section_pattern, ensure that there are no duplicate patterns in different execution regions in order 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 description 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 description
}

Note

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

Order of input section descriptors is not significant.

Copyright © 2007 ARM Limited. All rights reserved.	ARM DUI 0377A
PDF version

Home > Using Scatter-loading Description Files > Formal syntax of the scatter-loading description file > Input section description