LLVM Extensions

Introduction

This document describes extensions to tools and formats LLVM seeks compatibilitywith.

General Assembly Syntax

C99-style Hexadecimal Floating-point Constants

LLVM’s assemblers allow floating-point constants to be written in C99’shexadecimal format instead of decimal if desired.

  1. .section .data
  2. .float 0x1c2.2ap3

Machine-specific Assembly Syntax

X86/COFF-Dependent

Relocations

The following additional relocation types are supported:

@IMGREL (AT&T syntax only) generates an image-relative relocation thatcorresponds to the COFF relocation types IMAGE_REL_I386_DIR32NB (32-bit) orIMAGE_REL_AMD64_ADDR32NB (64-bit).

  1. .text
  2. fun:
  3.   mov foo@IMGREL(%ebx, %ecx, 4), %eax
  4.  
  5. .section .pdata
  6.   .long fun@IMGREL
  7.   .long (fun@imgrel + 0x3F)
  8.   .long $unwind$fun@imgrel

.secrel32 generates a relocation that corresponds to the COFF relocationtypes IMAGE_REL_I386_SECREL (32-bit) or IMAGE_REL_AMD64_SECREL (64-bit).

.secidx relocation generates an index of the section that containsthe target. It corresponds to the COFF relocation typesIMAGE_REL_I386_SECTION (32-bit) or IMAGE_REL_AMD64_SECTION (64-bit).

  1. .section .debug$S,"rn"
  2.   .long 4
  3.   .long 242
  4.   .long 40
  5.   .secrel32 _function_name + 0
  6.   .secidx   _function_name
  7.   ...

.linkonce Directive

Syntax:

.linkonce [ comdat type ]

Supported COMDAT types:

  • discard
  • Discards duplicate sections with the same COMDAT symbol. This is the defaultif no type is specified.
  • one_only
  • If the symbol is defined multiple times, the linker issues an error.
  • same_size
  • Duplicates are discarded, but the linker issues an error if any havedifferent sizes.
  • same_contents
  • Duplicates are discarded, but the linker issues an error if any duplicatesdo not have exactly the same content.
  • largest
  • Links the largest section from among the duplicates.
  • newest
  • Links the newest section from among the duplicates.
  1. .section .text$foo
  2. .linkonce
  3.   ...

.section Directive

MC supports passing the information in .linkonce at the end of.section. For example, these two codes are equivalent

  1. .section secName, "dr", discard, "Symbol1"
  2. .globl Symbol1
  3. Symbol1:
  4. .long 1
  1. .section secName, "dr"
  2. .linkonce discard
  3. .globl Symbol1
  4. Symbol1:
  5. .long 1

Note that in the combined form the COMDAT symbol is explicit. Thisextension exists to support multiple sections with the same name indifferent COMDATs:

  1. .section secName, "dr", discard, "Symbol1"
  2. .globl Symbol1
  3. Symbol1:
  4. .long 1
  5.  
  6. .section secName, "dr", discard, "Symbol2"
  7. .globl Symbol2
  8. Symbol2:
  9. .long 1

In addition to the types allowed with .linkonce, .section also acceptsassociative. The meaning is that the section is linked if a certain otherCOMDAT section is linked. This other section is indicated by the comdat symbolin this directive. It can be any symbol defined in the associated section, butis usually the associated section’s comdat.

The following restrictions apply to the associated section:

  1. It must be a COMDAT section.
  2. It cannot be another associative COMDAT section.

In the following example the symobl sym is the comdat symbol of .fooand .bar is associated to .foo.

  1. .section        .foo,"bw",discard, "sym"
  2. .section        .bar,"rd",associative, "sym"

MC supports these flags in the COFF .section directive:

  • b: BSS section (IMAGE_SCN_CNT_INITIALIZED_DATA)
  • d: Data section (IMAGE_SCN_CNT_UNINITIALIZED_DATA)
  • n: Section is not loaded (IMAGE_SCN_LNK_REMOVE)
  • r: Read-only
  • s: Shared section
  • w: Writable
  • x: Executable section
  • y: Not readable
  • D: Discardable (IMAGE_SCN_MEM_DISCARDABLE)

These flags are all compatible with gas, with the exception of the D flag,which gnu as does not support. For gas compatibility, sections with a namestarting with “.debug” are implicitly discardable.

ARM64/COFF-Dependent

Relocations

The following additional symbol variants are supported:

:secrel_lo12: generates a relocation that corresponds to the COFF relocationtypes IMAGE_REL_ARM64_SECREL_LOW12A or IMAGE_REL_ARM64_SECREL_LOW12L.

:secrel_hi12: generates a relocation that corresponds to the COFF relocationtype IMAGE_REL_ARM64_SECREL_HIGH12A.

  1. add x0, x0, :secrel_hi12:symbol
  2. ldr x0, [x0, :secrel_lo12:symbol]
  3.  
  4. add x1, x1, :secrel_hi12:symbol
  5. add x1, x1, :secrel_lo12:symbol
  6. ...

ELF-Dependent

.section Directive

In order to support creating multiple sections with the same name and comdat,it is possible to add an unique number at the end of the .section directive.For example, the following code creates two sections named .text.

  1. .section        .text,"ax",@progbits,unique,1
  2. nop
  3.  
  4. .section        .text,"ax",@progbits,unique,2
  5. nop

The unique number is not present in the resulting object at all. It is just usedin the assembler to differentiate the sections.

The ‘o’ flag is mapped to SHF_LINK_ORDER. If it is present, a symbolmust be given that identifies the section to be placed is the.sh_link.

  1. .section .foo,"a",@progbits
  2. .Ltmp:
  3. .section .bar,"ao",@progbits,.Ltmp

which is equivalent to just

  1. .section .foo,"a",@progbits
  2. .section .bar,"ao",@progbits,.foo

.linker-options Section (linker options)

In order to support passing linker options from the frontend to the linker, aspecial section of type SHT_LLVM_LINKER_OPTIONS (usually named.linker-options though the name is not significant as it is identified bythe type). The contents of this section is a simple pair-wise encoding ofdirectives for consideration by the linker. The strings are encoded as standardnull-terminated UTF-8 strings. They are emitted inline to avoid having thelinker traverse the object file for retrieving the value. The linker ispermitted to not honour the option and instead provide a warning/error to theuser that the requested option was not honoured.

The section has type SHT_LLVM_LINKER_OPTIONS and has the SHF_EXCLUDEflag to ensure that the section is treated as opaque by linkers which do notsupport the feature and will not be emitted into the final linked binary.

This would be equivalent to the follow raw assembly:

  1. .section ".linker-options","e",@llvm_linker_options
  2. .asciz "option 1"
  3. .asciz "value 1"
  4. .asciz "option 2"
  5. .asciz "value 2"

The following directives are specified:

  • lib

    The parameter identifies a library to be linked against. The library willbe looked up in the default and any specified library search paths(specified to this point).

  • libpath

    The paramter identifies an additional library search path to be consideredwhen looking up libraries after the inclusion of this option.

SHT_LLVM_DEPENDENT_LIBRARIES Section (Dependent Libraries)

This section contains strings specifying libraries to be added to the link bythe linker.

The section should be consumed by the linker and not written to the output.

The strings are encoded as standard null-terminated UTF-8 strings.

For example:

  1. .section ".deplibs","MS",@llvm_dependent_libraries,1
  2. .asciz "library specifier 1"
  3. .asciz "library specifier 2"

The interpretation of the library specifiers is defined by the consuming linker.

SHT_LLVM_CALL_GRAPH_PROFILE Section (Call Graph Profile)

This section is used to pass a call graph profile to the linker which can beused to optimize the placement of sections. It contains a sequence of(from symbol, to symbol, weight) tuples.

It shall have a type of SHT_LLVM_CALL_GRAPH_PROFILE (0x6fff4c02), shallhave the SHF_EXCLUDE flag set, the sh_link member shall hold the sectionheader index of the associated symbol table, and shall have a sh_entsize of16. It should be named .llvm.call-graph-profile.

The contents of the section shall be a sequence of Elf_CGProfile entries.

  1. typedef struct {
  2.   Elf_Word cgp_from;
  3.   Elf_Word cgp_to;
  4.   Elf_Xword cgp_weight;
  5. } Elf_CGProfile;
  • cgp_from
  • The symbol index of the source of the edge.
  • cgp_to
  • The symbol index of the destination of the edge.
  • cgp_weight
  • The weight of the edge.

This is represented in assembly as:

  1. .cg_profile from, to, 42

.cg_profile directives are processed at the end of the file. It is an errorif either from or to are undefined temporary symbols. If either symbolis a temporary symbol, then the section symbol is used instead. If eithersymbol is undefined, then that symbol is defined as if .weak symbol has beenwritten at the end of the file. This forces the symbol to show up in the symboltable.

SHT_LLVM_ADDRSIG Section (address-significance table)

This section is used to mark symbols as address-significant, i.e. the addressof the symbol is used in a comparison or leaks outside the translation unit. Ithas the same meaning as the absence of the LLVM attributes unnamed_addrand local_unnamed_addr.

Any sections referred to by symbols that are not marked as address-significantin any object file may be safely merged by a linker without breaking theaddress uniqueness guarantee provided by the C and C++ language standards.

The contents of the section are a sequence of ULEB128-encoded integersreferring to the symbol table indexes of the address-significant symbols.

There are two associated assembly directives:

  1. .addrsig

This instructs the assembler to emit an address-significance table. Withoutthis directive, all symbols are considered address-significant.

  1. .addrsig_sym sym

This marks sym as address-significant.

SHT_LLVM_SYMPART Section (symbol partition specification)

This section is used to mark symbols with the partition that theybelong to. An .llvm_sympart section consists of a null-terminated stringspecifying the name of the partition followed by a relocation referring tothe symbol that belongs to the partition. It may be constructed as follows:

  1. .section ".llvm_sympart","",@llvm_sympart
  2. .asciz "libpartition.so"
  3. .word symbol_in_partition

CodeView-Dependent

.cv_file Directive

  • Syntax:
  • .cvfile _FileNumber FileName [ checksum ] [ checksumkind ]

.cv_func_id Directive

Introduces a function ID that can be used with .cv_loc.

  • Syntax:
  • .cvfunc_id _FunctionId

.cv_inline_site_id Directive

Introduces a function ID that can be used with .cv_loc. Includesinlined at source location information for use in the line table of thecaller, whether the caller is a real function or another inlined call site.

  • Syntax:
  • .cvinline_site_id _FunctionId within Function inlinedat _FileNumber Line [ Colomn ]

.cv_loc Directive

The first number is a file number, must have been previously assigned with a.file directive, the second number is the line number and optionally thethird number is a column position (zero if not specified). The remainingoptional items are .loc sub-directives.

  • Syntax:
  • .cvloc _FunctionId FileNumber [ Line ] [ Column ] [ prologue_end ] [ isstmt _value ]

.cv_linetable Directive

  • Syntax:
  • .cvlinetable _FunctionId , FunctionStart , FunctionEnd

.cv_inline_linetable Directive

  • Syntax:
  • .cvinline_linetable _PrimaryFunctionId , FileNumber Line FunctionStart FunctionEnd

.cv_def_range Directive

The GapStart and GapEnd options may be repeated as needed.

  • Syntax:
  • .cvdef_range _RangeStart RangeEnd [ GapStart GapEnd ] , bytes

.cv_stringtable Directive

.cv_filechecksums Directive

.cv_filechecksumoffset Directive

  • Syntax:
  • .cvfilechecksumoffset _FileNumber

.cv_fpo_data Directive

  • Syntax:
  • .cvfpo_data _procsym

Target Specific Behaviour

X86

Relocations

@ABS8 can be applied to symbols which appear as immediate operands toinstructions that have an 8-bit immediate form for that operand. It causesthe assembler to use the 8-bit form and an 8-bit relocation (e.g. R_386_8or R_X86_64_8) for the symbol.

For example:

  1. cmpq $foo@ABS8, %rdi

This causes the assembler to select the form of the 64-bit cmpq instructionthat takes an 8-bit immediate operand that is sign extended to 64 bits, asopposed to cmpq $foo, %rdi which takes a 32-bit immediate operand. Thisis also not the same as cmpb $foo, %dil, which is an 8-bit comparison.

Windows on ARM

Stack Probe Emission

The reference implementation (Microsoft Visual Studio 2012) emits stack probesin the following fashion:

  1. movw r4, #constant
  2. bl __chkstk
  3. sub.w sp, sp, r4

However, this has the limitation of 32 MiB (±16MiB). In order to accommodatelarger binaries, LLVM supports the use of -mcmodel=large to allow a 4GiBrange via a slight deviation. It will generate an indirect jump as follows:

  1. movw r4, #constant
  2. movw r12, :lower16:__chkstk
  3. movt r12, :upper16:__chkstk
  4. blx r12
  5. sub.w sp, sp, r4

Variable Length Arrays

The reference implementation (Microsoft Visual Studio 2012) does not permit theemission of Variable Length Arrays (VLAs).

The Windows ARM Itanium ABI extends the base ABI by adding support for emittinga dynamic stack allocation. When emitting a variable stack allocation, a callto __chkstk is emitted unconditionally to ensure that guard pages are setupproperly. The emission of this stack probe emission is handled similar to thestandard stack probe emission.

The MSVC environment does not emit code for VLAs currently.

Windows on ARM64

Stack Probe Emission

The reference implementation (Microsoft Visual Studio 2017) emits stack probesin the following fashion:

  1. mov x15, #constant
  2. bl __chkstk
  3. sub sp, sp, x15, lsl #4

However, this has the limitation of 256 MiB (±128MiB). In order to accommodatelarger binaries, LLVM supports the use of -mcmodel=large to allow a 8GiB(±4GiB) range via a slight deviation. It will generate an indirect jump asfollows:

  1. mov x15, #constant
  2. adrp x16, __chkstk
  3. add x16, x16, :lo12:__chkstk
  4. blr x16
  5. sub sp, sp, x15, lsl #4