as: Literal Directive

1 
1 9.55.5.4 literal
1 ................
1 
1 The '.literal' directive is used to define literal pool data, i.e.,
1 read-only 32-bit data accessed via 'L32R' instructions.
1 
1          .literal LABEL, VALUE[, VALUE...]
1 
1    This directive is similar to the standard '.word' directive, except
1 that the actual location of the literal data is determined by the
1 assembler and linker, not by the position of the '.literal' directive.
1 Using this directive gives the assembler freedom to locate the literal
1 data in the most appropriate place and possibly to combine identical
1 literals.  For example, the code:
1 
1          entry sp, 40
1          .literal .L1, sym
1          l32r    a4, .L1
1 
1    can be used to load a pointer to the symbol 'sym' into register 'a4'.
1 The value of 'sym' will not be placed between the 'ENTRY' and 'L32R'
1 instructions; instead, the assembler puts the data in a literal pool.
1 
1    Literal pools are placed by default in separate literal sections;
11 however, when using the '--text-section-literals' option (⇒Command
 Line Options Xtensa Options.), the literal pools for PC-relative mode
1 'L32R' instructions are placed in the current section.(1)  These text
1 section literal pools are created automatically before 'ENTRY'
11 instructions and manually after '.literal_position' directives (⇒
 literal_position Literal Position Directive.).  If there are no
1 preceding 'ENTRY' instructions, explicit '.literal_position' directives
1 must be used to place the text section literal pools; otherwise, 'as'
1 will report an error.
1 
1    When literals are placed in separate sections, the literal section
1 names are derived from the names of the sections where the literals are
1 defined.  The base literal section names are '.literal' for PC-relative
1 mode 'L32R' instructions and '.lit4' for absolute mode 'L32R'
1 instructions (⇒absolute-literals Absolute Literals Directive.).
1 These base names are used for literals defined in the default '.text'
1 section.  For literals defined in other sections or within the scope of
11 a 'literal_prefix' directive (⇒literal_prefix Literal Prefix
 Directive.), the following rules determine the literal section name:
1 
1   1. If the current section is a member of a section group, the literal
1      section name includes the group name as a suffix to the base
1      '.literal' or '.lit4' name, with a period to separate the base name
1      and group name.  The literal section is also made a member of the
1      group.
1 
1   2. If the current section name (or 'literal_prefix' value) begins with
1      "'.gnu.linkonce.KIND.'", the literal section name is formed by
1      replacing "'.KIND'" with the base '.literal' or '.lit4' name.  For
1      example, for literals defined in a section named
1      '.gnu.linkonce.t.func', the literal section will be
1      '.gnu.linkonce.literal.func' or '.gnu.linkonce.lit4.func'.
1 
1   3. If the current section name (or 'literal_prefix' value) ends with
1      '.text', the literal section name is formed by replacing that
1      suffix with the base '.literal' or '.lit4' name.  For example, for
1      literals defined in a section named '.iram0.text', the literal
1      section will be '.iram0.literal' or '.iram0.lit4'.
1 
1   4. If none of the preceding conditions apply, the literal section name
1      is formed by adding the base '.literal' or '.lit4' name as a suffix
1      to the current section name (or 'literal_prefix' value).
1 
1    ---------- Footnotes ----------
1 
1    (1) Literals for the '.init' and '.fini' sections are always placed
1 in separate sections, even when '--text-section-literals' is enabled.
1