Arm Compiler armclang Reference Guide : 9.7 Section directives

9.7 Section directives

The section directives instruct the assembler to change the ELF section that code and data are emitted into.

Syntax

.section name [, "flags" [, %type [, entry_size] [, group_name [, linkage]] [, link_order_symbol] [, unique, unique_id] ]]

.pushsection .section name [, "flags" [, %type [, entry_size] [, group_name [, linkage]] [, link_order_symbol] [, unique, unique_id] ]]

.popsection

.text

.data

.rodata

.bss

Description

name

The name argument gives the name of the section to switch to.

By default, if the name is identical to a previous section, or one of the built-in sections, the assembler will switch back to that section. Any code or data that is assembled will be appended to the end of that section. The unique-id argument can be used to override this behavior.

flags

The optional flags argument is a quoted string containing any of the following characters, which correspond to the sh_flags field in the ELF section header.

Table 9-14 Section flags

Flag	Meaning
`a`	SHF_ALLOC: the section is allocatable.
`w`	SHF_WRITE: the section is writable.
`y`	SHF_ARM_PURECODE: the section is not readable.
`x`	SHF_EXECINSTR: the section is executable.
`o`	SHF_LINK_ORDER: the section has a link-order restriction.
`M`	SHF_MERGE: the section is mergeable.
`S`	SHF_STRINGS: the section contains null-terminated string.
`T`	SHF_TLS: the section is thread-local storage.
`G`	SHF_GROUP: the section is a member of a section group.
`?`	if the previous section was part of a group, this section is in the same group, otherwise ignored.

The flags can be specified as a numeric value, with the same encoding as the sh_flags field in the ELF section header. This cannot be combined with the flag characters listed above. When using this syntax, the quotes around the flags value are still required.

Note:

Certain flags need extra arguments, as described in the respective arguments.

type

The optional type argument is accepted with two different syntaxes: %type and "type". It corresponds to the sh_type field in the ELF section header. The following values for the type argument are accepted:

Table 9-15 Section Type

Argument	ELF type	Meaning
`%progbits`	`SHT_PROGBITS`	Section contains initialized data and/or instructions.
`%nobits`	`SHT_NOBITS`	Section consists only of zero-initialized data.
`%note`	`SHT_NOTE`	Section contains information that the linker or loader use to check compatibility.
`%init_array`	`SHT_INIT_ARRAY`	Section contains an array of pointers to initialization functions.
`%fini_array`	`SHT_FINI_ARRAY`	Section contains an array of pointers to termination functions.
`%preinit_array`	`SHT_PREINIT_ARRAY`	Section contains an array of pointers to pre-initialization functions.

The type can be specified as a numeric value, with the same encoding as the sh_type field in the ELF section header. When using this syntax, the quotes around the type value are still required.

entry_size

If the M flag is specified, the entry_size argument is required. This argument must be an integer value, which is the size of the records that are contained within this section, that the linker can merge.

group_name

If the G flag is specified, the group_name argument is required. This argument is a symbol name to be used as the signature to identify the section group. All sections in the same object file and with the same group_name are part of the same section group.

If the ? flag is specified, the section is implicitly in the same group as the previous section, and the group_name and linkage options are not accepted.

It is an error to specify both the G and ? flags on the same section.

linkage

If the G flag is specified, the optional linkage argument is allowed. The only valid value for this argument is comdat, which has the same effect as not providing the linkage argument. If any arguments after the group_name and linkage arguments are to be provided, then the linkage argument must be provided.

If the ? flag is specified, the section is implicitly in the same group as the previous section, and the group_name and linkage options are not accepted.

It is an error to specify both the G and ? flags on the same section.

link_order_symbol

If the o flag is specified, the link_order_symbol argument is required. This argument must be a symbol which is defined earlier in the same file. If multiple sections with the o flag are present at link time, the linker ensures that they are in the same order in the image as the sections that define the symbols they reference.

unique and unique_id

If the optional unique argument is provided, then the unique_id argument must also be provided. This argument should be a constant expression which evaluates to a positive integer. If a section has previously been created with the same name and unique ID, then the assembler will switch to the existing section, appending content to it. Otherwise, a new section is created. Sections without a unique ID specified will never be merged with sections that do have one. This allows creating multiple sections with the same name. The exact value of the unique ID is not important, and it has no effect on the generated object file.

Operation

The .section directive switches the current target section to the one described by its arguments. The .pushsection directive pushes the current target section onto a stack, and switches to the section described by its arguments. The .popsection directive takes no arguments, and reverts the current target section to the previous one on the stack. The rest of the directives (.text, .data, .rodata, .bss) switch to one of the built-in sections.

If continuing a previous section, and the flags, type, or other arguments do not match the previous definition of the section, then the arguments of the current .section directive will have no effect on the section. Instead, the assembler uses the arguments from the previous .section directive. The assembler does not currently emit a diagnostic when this happens.

Default

Some section names and section name prefixes implicitly have some flags set. Additional flags can be set using the flags argument, but it is not possible to clear these implicit flags. The section names that have implicit flags are listed in the table here. For sections names not mentioned in the table, the default is to have no flags.

If the %type argument is not provided, the type is inferred from the section name. For sections names not mentioned in the table here, the default section type is %progbits.

Table 9-16 Sections with implicit flags and default types

Section name	Implicit Flags	Default Type
`.rodata`	a	`%progbits`
`.text`	ax	`%progbits`
`.init`	ax	`%progbits`
`.fini`	ax	`%progbits`
`.data`	aw	`%progbits`
`.bss`	aw	`%nobits`
`.init_array`	No default	`%init_array`
`.fini_array`	No default	`%fini_array`
`.preinit_array`	No default	`%preinit_array`
`.tdata`	awT	`%progbits`
`.tbss`	awT	`%nobits`
`.note*`	No default	`%note`

Examples

Splitting code and data into the built-in .text and .data sections. The linker can place these sections independently, for example to place the code in flash memory, and the writable data in RAM.

     .text
    get_value:
      movw r0, #:lower16:value
      movt r0, #:upper16:value
      ldr r0, [r0]
      bx lr

      .data
    value:
      .word 42

Creating a section containing constant, mergeable records. This section contains a series of 8-byte records, where the linker is allowed to merge two records with identical content (possibly coming from different object files) into one record to reduce the image size.

      .section mergable, "aM", %progbits, 8
    entry1:
      .word label1
      .word 42
    entry2:
      .word label2
      .word 0x1234

Creating two sections with the same name:

      .section .data, "aw", %progbits, unique, 1
      .word 1
      .section .data, "aw", %progbits, unique, 2
      .word 2

Creating a section group containing two sections. Here, the G flag is used for the first section, using the group_signature symbol. The second section uses the ? flag to simplify making it part of the same group. Any further sections in this file using the G flag and group_signature symbol are placed in the same group.

      .section foo, "axG", %progbits, group_signature
    get_value:
      movw r0, #:lower16:value
      movt r0, #:upper16:value
      ldr r0, [r0]
      bx lr

      .section bar, "aw?"
      .local value
    value:
      .word 42

Non-Confidential	PDF version	DUI0774J
Copyright © 2014–2017, 2019 Arm Limited or its affiliates. All rights reserved.