You copied the Doc URL to your clipboard.

Placing unassigned sections with the .ANY module selector

The linker attempts to place input sections into specific execution regions. For any input sections that cannot be resolved, and where the placement of those sections is not important, you can use the .ANY module selector in the scatter file.

In most cases, using a single .ANY selector is equivalent to using the * module selector. However, unlike *, you can specify .ANY in multiple execution regions.

Default rules for placing unassigned sections

By default, the linker places unassigned sections using the following criteria:

  • Place an unassigned section in the execution region that currently has the most free space. You can specify a maximum amount of space to use for unassigned sections with the exection region attribute ANY_SIZE.

  • Sort sections in descending size order.

Placement rules when using multiple .ANY selectors

If more than one .ANY selector is present in a scatter file, the linker takes the unassigned section with the largest size and assigns the section to the most specific .ANY execution region that has enough free space. For example, .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.

Prioritizing .ANY sections

You can give a priority ordering if you have multiple .ANY sections with the .ANYnum selector, where num is a positive integer from zero upwards. The highest priority is given to the selector with the highest integer.

The following example shows how to use .ANYnum:

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

Controlling the placement of input sections for multiple .ANY selectors

You can modify how the linker places unassigned input sections when using multiple .ANY selectors by using a different placement algorithm or a different sort order. The following command-line options are available:

  • --any_placement=algorithm, where algorithm is one of first_fit, worst_fit, best_fit, or next_fit

  • --any_sort_order=order, where order is one of cmdline or descending_size.

Use first_fit when you want to fill regions in order.

Use best_fit when you want to fill regions to their maximum.

Use worst_fit when you want to fill regions evenly. With equal sized regions and sections worst_fit fills regions cyclically.

Use next_fit when you need a more deterministic fill pattern.

If the linker attempts to fill a region to its limit, as it does with first_fit and best_fit, it might overfill the region. This is because linker-generated content such as padding and veneers are not known until sections have been assigned to .ANY selectors. If this occurs you might see the following error:

Error: L6220E: Execution region regionname size (size bytes) exceeds limit (limit bytes).

The --any_contingency option prevents the linker from filling the region up to its maximum. It reserves a portion of the region's size for linker-generated content and fills this contingency area only if no other regions have space. It is enabled by default for the first_fit and best_fit algorithms, because they are most likely to exhibit this behavior.

Specifying the maximum size permitted for placing unassigned sections

The execution region attribute ANY_SIZE max_size enables you to specify the maximum size in a region that armlink can fill with unassigned sections.

Be aware of the following restrictions when using this keyword:

  • max_size must be less than or equal to the region size

  • you can use ANY_SIZE on a region without a .ANY selector but it is ignored by armlink.

When ANY_SIZE is present, armlink:

  • Does not override a given .ANY size. That is, it does not reduce the priority then try to fit more sections in later.

  • Never recalculates contingency.

  • Never assigns sections in the contingency space.

ANY_SIZE does not require --any_contingency to be specified. However, when --any_contingency is specified and ANY_SIZE is not, armlink attempts to adjust contingencies. The aims are to:

  • never overflow a .ANY region

  • never refuse to place a section in a contingency reserved space.

If you specify --any_contingency on the command line, it is ignored for regions that have ANY_SIZE specified. It is used as normal for regions that do not have ANY_SIZE specified.

The following example shows how to use ANY_SIZE:

LOAD_REGION 0x0 0x3000
   ER_1 0x0 ANY_SIZE 0xF00 0x1000
   ER_2 0x0 ANY_SIZE 0xFB0 0x1000
   ER_3 0x0 ANY_SIZE 0x1000 0x1000

In this example:

  • ER_1 has 0x100 reserved for linker-generated content.

  • ER_2 has 0x50 reserved for linker-generated content. That is about the same as the automatic contingency of --any_contingency.

  • ER_3 has no reserved space. Therefore 100% of the region is filled, with no contingency for veneers. Omitting the ANY_SIZE parameter causes 98% of the region to be filled, with a two percent contingency for veneers.