16.5. The SECTIONS Directive

You can convert specific sections of the object file by name with the hex conversion utility SECTIONS directive. You can also specify those sections that you want to locate in ROM at a different address than the load address specified in the linker command file. If you:

  • Use a SECTIONS directive, the utility converts only the sections that you list in the directive and ignores all other sections in the object file.

  • Do not use a SECTIONS directive, the utility converts all initialized sections that fall within the configured memory.

Uninitialized sections are never converted, whether or not you specify them in a SECTIONS directive.

Note

Sections Generated by the C/C++ Compiler The Arm C/C++ compiler automatically generates these sections:

  • Initialized sections: .text, .const, .rodata, .cinit, and .switch

  • Uninitialized sections: .bss, .stack, and .sysmem

Use the SECTIONS directive in a command file. (See Invoking the Hex Conversion Utility With a Command File.) The general syntax is:

SECTIONS
{

    oname(sname)[:] [paddr=value]
    oname(sname)[:] [paddr=boot]
    oname(sname)[:] [boot]
    ...
}

  • SECTIONS begins the directive definition.

  • oname identifies the object filename the section is located within. The filename is optional when only a single input file is given, but required otherwise.

  • sname identifies a section in the input file. If you specify a section that does not exist, the utility issues a warning and ignores the name.

  • paddr=value specifies the physical ROM address at which this section should be located. This value overrides the section load address given by the linker. This value must be a decimal, octal, or hexadecimal constant. It can also be the word boot (to indicate a boot table section for use with a boot loader). If your file contains multiple sections, and if one section uses a paddr parameter, then all sections must use a paddr parameter.

  • boot configures a section for loading by a boot loader. This is equivalent to using paddr=boot. Boot sections have a physical address determined by the location of the boot table. The origin of the boot table is specified with the --bootorg option.

For more similarity with the linker’s SECTIONS directive, you can use colons after the section names (in place of the equal sign on the boot keyboard). For example, the following statements are equivalent:

SECTIONS { .text: .data: boot }
SECTIONS { .text: .data = boot }

In the example below, the object file contains six initialized sections: .text, .data, .const, .rodata, .vectors, .coeff, and .tables. Suppose you want only .text and .data to be converted. Use a SECTIONS directive to specify this:

SECTIONS { .text: .data: }

To configure both of these sections for boot loading, add the boot keyword:

SECTIONS { .text = boot .data = boot }