llvm/docs/Extensions.rst

   1 ===============
   2 LLVM Extensions
   3 ===============
   4
   5 .. contents::
   6    :local:
   7
   8 .. toctree::
   9    :hidden:
  10
  11 Introduction
  12 ============
  13
  14 This document describes extensions to tools and formats LLVM seeks compatibility
  15 with.
  16
  17 General Assembly Syntax
  18 ===========================
  19
  20 C99-style Hexadecimal Floating-point Constants
  21 ----------------------------------------------
  22
  23 LLVM's assemblers allow floating-point constants to be written in C99's
  24 hexadecimal format instead of decimal if desired.
  25
  26 .. code-block:: gas
  27
  28   .section .data
  29   .float 0x1c2.2ap3
  30
  31 Machine-specific Assembly Syntax
  32 ================================
  33
  34 X86/COFF-Dependent
  35 ------------------
  36
  37 Relocations
  38 ^^^^^^^^^^^
  39
  40 The following additional relocation types are supported:
  41
  42 **@IMGREL** (AT&T syntax only) generates an image-relative relocation that
  43 corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or
  44 ``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).
  45
  46 .. code-block:: text
  47
  48   .text
  49   fun:
  50     mov foo@IMGREL(%ebx, %ecx, 4), %eax
  51
  52   .section .pdata
  53     .long fun@IMGREL
  54     .long (fun@imgrel + 0x3F)
  55     .long $unwind$fun@imgrel
  56
  57 **.secrel32** generates a relocation that corresponds to the COFF relocation
  58 types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit).
  59
  60 **.secidx** relocation generates an index of the section that contains
  61 the target.  It corresponds to the COFF relocation types
  62 ``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit).
  63
  64 .. code-block:: none
  65
  66   .section .debug$S,"rn"
  67     .long 4
  68     .long 242
  69     .long 40
  70     .secrel32 _function_name + 0
  71     .secidx   _function_name
  72     ...
  73
  74 ``.linkonce`` Directive
  75 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  76
  77 Syntax:
  78
  79    ``.linkonce [ comdat type ]``
  80
  81 Supported COMDAT types:
  82
  83 ``discard``
  84    Discards duplicate sections with the same COMDAT symbol. This is the default
  85    if no type is specified.
  86
  87 ``one_only``
  88    If the symbol is defined multiple times, the linker issues an error.
  89
  90 ``same_size``
  91    Duplicates are discarded, but the linker issues an error if any have
  92    different sizes.
  93
  94 ``same_contents``
  95    Duplicates are discarded, but the linker issues an error if any duplicates
  96    do not have exactly the same content.
  97
  98 ``largest``
  99    Links the largest section from among the duplicates.
 100
 101 ``newest``
 102    Links the newest section from among the duplicates.
 103
 104
 105 .. code-block:: gas
 106
 107   .section .text$foo
 108   .linkonce
 109     ...
 110
 111 ``.section`` Directive
 112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 113
 114 MC supports passing the information in ``.linkonce`` at the end of
 115 ``.section``. For example,  these two codes are equivalent
 116
 117 .. code-block:: gas
 118
 119   .section secName, "dr", discard, "Symbol1"
 120   .globl Symbol1
 121   Symbol1:
 122   .long 1
 123
 124 .. code-block:: gas
 125
 126   .section secName, "dr"
 127   .linkonce discard
 128   .globl Symbol1
 129   Symbol1:
 130   .long 1
 131
 132 Note that in the combined form the COMDAT symbol is explicit. This
 133 extension exists to support multiple sections with the same name in
 134 different COMDATs:
 135
 136
 137 .. code-block:: gas
 138
 139   .section secName, "dr", discard, "Symbol1"
 140   .globl Symbol1
 141   Symbol1:
 142   .long 1
 143
 144   .section secName, "dr", discard, "Symbol2"
 145   .globl Symbol2
 146   Symbol2:
 147   .long 1
 148
 149 In addition to the types allowed with ``.linkonce``, ``.section`` also accepts
 150 ``associative``. The meaning is that the section is linked  if a certain other
 151 COMDAT section is linked. This other section is indicated by the comdat symbol
 152 in this directive. It can be any symbol defined in the associated section, but
 153 is usually the associated section's comdat.
 154
 155    The following restrictions apply to the associated section:
 156
 157    1. It must be a COMDAT section.
 158    2. It cannot be another associative COMDAT section.
 159
 160 In the following example the symbol ``sym`` is the comdat symbol of ``.foo``
 161 and ``.bar`` is associated to ``.foo``.
 162
 163 .. code-block:: gas
 164
 165         .section        .foo,"bw",discard, "sym"
 166         .section        .bar,"rd",associative, "sym"
 167
 168 MC supports these flags in the COFF ``.section`` directive:
 169
 170   - ``b``: BSS section (``IMAGE_SCN_CNT_INITIALIZED_DATA``)
 171   - ``d``: Data section (``IMAGE_SCN_CNT_UNINITIALIZED_DATA``)
 172   - ``n``: Section is not loaded (``IMAGE_SCN_LNK_REMOVE``)
 173   - ``r``: Read-only
 174   - ``s``: Shared section
 175   - ``w``: Writable
 176   - ``x``: Executable section
 177   - ``y``: Not readable
 178   - ``D``: Discardable (``IMAGE_SCN_MEM_DISCARDABLE``)
 179
 180 These flags are all compatible with gas, with the exception of the ``D`` flag,
 181 which gnu as does not support. For gas compatibility, sections with a name
 182 starting with ".debug" are implicitly discardable.
 183
 184
 185 ARM64/COFF-Dependent
 186 --------------------
 187
 188 Relocations
 189 ^^^^^^^^^^^
 190
 191 The following additional symbol variants are supported:
 192
 193 **:secrel_lo12:** generates a relocation that corresponds to the COFF relocation
 194 types ``IMAGE_REL_ARM64_SECREL_LOW12A`` or ``IMAGE_REL_ARM64_SECREL_LOW12L``.
 195
 196 **:secrel_hi12:** generates a relocation that corresponds to the COFF relocation
 197 type ``IMAGE_REL_ARM64_SECREL_HIGH12A``.
 198
 199 .. code-block:: gas
 200
 201     add x0, x0, :secrel_hi12:symbol
 202     ldr x0, [x0, :secrel_lo12:symbol]
 203
 204     add x1, x1, :secrel_hi12:symbol
 205     add x1, x1, :secrel_lo12:symbol
 206     ...
 207
 208
 209 ELF-Dependent
 210 -------------
 211
 212 ``.section`` Directive
 213 ^^^^^^^^^^^^^^^^^^^^^^
 214
 215 In order to support creating multiple sections with the same name and comdat,
 216 it is possible to add an unique number at the end of the ``.section`` directive.
 217 For example, the following code creates two sections named ``.text``.
 218
 219 .. code-block:: gas
 220
 221         .section        .text,"ax",@progbits,unique,1
 222         nop
 223
 224         .section        .text,"ax",@progbits,unique,2
 225         nop
 226
 227
 228 The unique number is not present in the resulting object at all. It is just used
 229 in the assembler to differentiate the sections.
 230
 231 The 'o' flag is mapped to SHF_LINK_ORDER. If it is present, a symbol
 232 must be given that identifies the section to be placed is the
 233 .sh_link.
 234
 235 .. code-block:: gas
 236
 237         .section .foo,"a",@progbits
 238         .Ltmp:
 239         .section .bar,"ao",@progbits,.Ltmp
 240
 241 which is equivalent to just
 242
 243 .. code-block:: gas
 244
 245         .section .foo,"a",@progbits
 246         .section .bar,"ao",@progbits,.foo
 247
 248 ``.linker-options`` Section (linker options)
 249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 250
 251 In order to support passing linker options from the frontend to the linker, a
 252 special section of type ``SHT_LLVM_LINKER_OPTIONS`` (usually named
 253 ``.linker-options`` though the name is not significant as it is identified by
 254 the type).  The contents of this section is a simple pair-wise encoding of
 255 directives for consideration by the linker.  The strings are encoded as standard
 256 null-terminated UTF-8 strings.  They are emitted inline to avoid having the
 257 linker traverse the object file for retrieving the value.  The linker is
 258 permitted to not honour the option and instead provide a warning/error to the
 259 user that the requested option was not honoured.
 260
 261 The section has type ``SHT_LLVM_LINKER_OPTIONS`` and has the ``SHF_EXCLUDE``
 262 flag to ensure that the section is treated as opaque by linkers which do not
 263 support the feature and will not be emitted into the final linked binary.
 264
 265 This would be equivalent to the follow raw assembly:
 266
 267 .. code-block:: gas
 268
 269   .section ".linker-options","e",@llvm_linker_options
 270   .asciz "option 1"
 271   .asciz "value 1"
 272   .asciz "option 2"
 273   .asciz "value 2"
 274
 275 The following directives are specified:
 276
 277   - lib
 278
 279     The parameter identifies a library to be linked against.  The library will
 280     be looked up in the default and any specified library search paths
 281     (specified to this point).
 282
 283   - libpath
 284
 285     The parameter identifies an additional library search path to be considered
 286     when looking up libraries after the inclusion of this option.
 287
 288 ``SHT_LLVM_DEPENDENT_LIBRARIES`` Section (Dependent Libraries)
 289 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 290
 291 This section contains strings specifying libraries to be added to the link by
 292 the linker.
 293
 294 The section should be consumed by the linker and not written to the output.
 295
 296 The strings are encoded as standard null-terminated UTF-8 strings.
 297
 298 For example:
 299
 300 .. code-block:: gas
 301
 302   .section ".deplibs","MS",@llvm_dependent_libraries,1
 303   .asciz "library specifier 1"
 304   .asciz "library specifier 2"
 305
 306 The interpretation of the library specifiers is defined by the consuming linker.
 307
 308 ``SHT_LLVM_CALL_GRAPH_PROFILE`` Section (Call Graph Profile)
 309 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 310
 311 This section is used to pass a call graph profile to the linker which can be
 312 used to optimize the placement of sections.  It contains a sequence of
 313 (from symbol, to symbol, weight) tuples.
 314
 315 It shall have a type of ``SHT_LLVM_CALL_GRAPH_PROFILE`` (0x6fff4c02), shall
 316 have the ``SHF_EXCLUDE`` flag set, the ``sh_link`` member shall hold the section
 317 header index of the associated symbol table, and shall have a ``sh_entsize`` of
 318 16.  It should be named ``.llvm.call-graph-profile``.
 319
 320 The contents of the section shall be a sequence of ``Elf_CGProfile`` entries.
 321
 322 .. code-block:: c
 323
 324   typedef struct {
 325     Elf_Word cgp_from;
 326     Elf_Word cgp_to;
 327     Elf_Xword cgp_weight;
 328   } Elf_CGProfile;
 329
 330 cgp_from
 331   The symbol index of the source of the edge.
 332
 333 cgp_to
 334   The symbol index of the destination of the edge.
 335
 336 cgp_weight
 337   The weight of the edge.
 338
 339 This is represented in assembly as:
 340
 341 .. code-block:: gas
 342
 343   .cg_profile from, to, 42
 344
 345 ``.cg_profile`` directives are processed at the end of the file.  It is an error
 346 if either ``from`` or ``to`` are undefined temporary symbols.  If either symbol
 347 is a temporary symbol, then the section symbol is used instead.  If either
 348 symbol is undefined, then that symbol is defined as if ``.weak symbol`` has been
 349 written at the end of the file.  This forces the symbol to show up in the symbol
 350 table.
 351
 352 ``SHT_LLVM_ADDRSIG`` Section (address-significance table)
 353 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 354
 355 This section is used to mark symbols as address-significant, i.e. the address
 356 of the symbol is used in a comparison or leaks outside the translation unit. It
 357 has the same meaning as the absence of the LLVM attributes ``unnamed_addr``
 358 and ``local_unnamed_addr``.
 359
 360 Any sections referred to by symbols that are not marked as address-significant
 361 in any object file may be safely merged by a linker without breaking the
 362 address uniqueness guarantee provided by the C and C++ language standards.
 363
 364 The contents of the section are a sequence of ULEB128-encoded integers
 365 referring to the symbol table indexes of the address-significant symbols.
 366
 367 There are two associated assembly directives:
 368
 369 .. code-block:: gas
 370
 371   .addrsig
 372
 373 This instructs the assembler to emit an address-significance table. Without
 374 this directive, all symbols are considered address-significant.
 375
 376 .. code-block:: gas
 377
 378   .addrsig_sym sym
 379
 380 If ``sym`` is not otherwise referenced or defined anywhere else in the file,
 381 this directive is a no-op. Otherwise, mark ``sym`` as address-significant.
 382
 383 ``SHT_LLVM_SYMPART`` Section (symbol partition specification)
 384 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 385
 386 This section is used to mark symbols with the `partition`_ that they
 387 belong to. An ``.llvm_sympart`` section consists of a null-terminated string
 388 specifying the name of the partition followed by a relocation referring to
 389 the symbol that belongs to the partition. It may be constructed as follows:
 390
 391 .. code-block:: gas
 392
 393   .section ".llvm_sympart","",@llvm_sympart
 394   .asciz "libpartition.so"
 395   .word symbol_in_partition
 396
 397 .. _partition: https://lld.llvm.org/Partitions.html
 398
 399 ``SHT_LLVM_BB_ADDR_MAP`` Section (basic block address map)
 400 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 401 This section stores the binary address of basic blocks along with other related
 402 metadata. This information can be used to map binary profiles (like perf
 403 profiles) directly to machine basic blocks.
 404 This section is emitted with ``-basic-block-sections=labels`` and will contain
 405 a BB address map table for every function.
 406
 407 The ``SHT_LLVM_BB_ADDR_MAP`` type provides backward compatibility to allow
 408 reading older versions of the BB address map generated by older compilers. Each
 409 function entry starts with a version byte which specifies the encoding version
 410 to use. The following versioning schemes are currently supported.
 411
 412 Version 1 (newest): basic block address offsets are computed relative to the end
 413 of previous blocks.
 414
 415 Example:
 416
 417 .. code-block:: gas
 418
 419   .section  ".llvm_bb_addr_map","",@llvm_bb_addr_map
 420   .byte     1                             # version number
 421   .byte     0                             # feature byte (reserved for future use)
 422   .quad     .Lfunc_begin0                 # address of the function
 423   .byte     2                             # number of basic blocks
 424   # BB record for BB_0
 425    .uleb128  .Lfunc_beign0-.Lfunc_begin0  # BB_0 offset relative to function entry (always zero)
 426    .uleb128  .LBB_END0_0-.Lfunc_begin0    # BB_0 size
 427    .byte     x                            # BB_0 metadata
 428   # BB record for BB_1
 429    .uleb128  .LBB0_1-.LBB_END0_0          # BB_1 offset relative to the end of last block (BB_0).
 430    .uleb128  .LBB_END0_1-.LBB0_1          # BB_1 size
 431    .byte     y                            # BB_1 metadata
 432
 433 Version 0: basic block address offsets are computed relative to the function
 434 address. This uses the unversioned ``SHT_LLVM_BB_ADDR_MAP_V0`` section type and
 435 is semantically equivalent to using ``SHT_LLVM_BB_ADDR_MAP`` with a zero
 436 version field.
 437
 438 Example:
 439
 440 .. code-block:: gas
 441
 442   .section  ".llvm_bb_addr_map","",@llvm_bb_addr_map_v0
 443   .quad     .Lfunc_begin0                 # address of the function
 444   .byte     2                             # number of basic blocks
 445   # BB record for BB_0
 446    .uleb128  .Lfunc_beign0-.Lfunc_begin0  # BB_0 offset relative to the function entry (always zero)
 447    .uleb128  .LBB_END0_0-.Lfunc_begin0    # BB_0 size
 448    .byte     x                            # BB_0 metadata
 449   # BB record for BB_1
 450    .uleb128  .LBB0_1-.Lfunc_begin0        # BB_1 offset relative to the function entry
 451    .uleb128  .LBB_END0_1-.LBB0_1          # BB_1 size
 452    .byte     y                            # BB_1 metadata
 453
 454 PGO Analysis Map
 455 """"""""""""""""
 456
 457 PGO related analysis data can be emitted after each function within the
 458 ``SHT_LLVM_BB_ADDR_MAP`` through the optional ``pgo-analysis-map`` flag.
 459 Supported analyses currently are Function Entry Count, Basic Block Frequencies,
 460 and Branch Probabilities.
 461
 462 Each analysis is enabled or disabled via a bit in the feature byte. Currently
 463 those bits are:
 464
 465 #. Function Entry Count - Number of times the function was called as taken
 466    from a PGO profile. This will always be zero if PGO was not used or the
 467    function was not encountered in the profile.
 468
 469 #. Basic Block Frequencies - Encoded as raw block frequency value taken from
 470    MBFI analysis. This value is an integer that encodes the relative frequency
 471    compared to the entry block. More information can be found in
 472    'llvm/Support/BlockFrequency.h'.
 473
 474 #. Branch Probabilities - Encoded as raw numerator for branch probability
 475    taken from MBPI analysis. This value is the numerator for a fixed point ratio
 476    defined in 'llvm/Support/BranchProbability.h'. It indicates the probability
 477    that the block is followed by a given successor block during execution.
 478
 479 This extra data requires version 2 or above. This is necessary since successors
 480 of basic blocks won't know their index but will know their BB ID.
 481
 482 Example of BBAddrMap with PGO data:
 483
 484 .. code-block:: gas
 485
 486   .section  ".llvm_bb_addr_map","",@llvm_bb_addr_map
 487   .byte     2                             # version number
 488   .byte     7                             # feature byte - PGO analyses enabled mask
 489   .quad     .Lfunc_begin0                 # address of the function
 490   .uleb128  4                             # number of basic blocks
 491   # BB record for BB_0
 492    .uleb128  0                            # BB_0 BB ID
 493    .uleb128  .Lfunc_begin0-.Lfunc_begin0  # BB_0 offset relative to function entry (always zero)
 494    .uleb128  .LBB_END0_0-.Lfunc_begin0    # BB_0 size
 495    .byte     0x18                         # BB_0 metadata (multiple successors)
 496   # BB record for BB_1
 497    .uleb128  1                            # BB_1 BB ID
 498    .uleb128  .LBB0_1-.LBB_END0_0          # BB_1 offset relative to the end of last block (BB_0).
 499    .uleb128  .LBB_END0_1-.LBB0_1          # BB_1 size
 500    .byte     0x0                          # BB_1 metadata (two successors)
 501   # BB record for BB_2
 502    .uleb128  2                            # BB_2 BB ID
 503    .uleb128  .LBB0_2-.LBB_END1_0          # BB_2 offset relative to the end of last block (BB_1).
 504    .uleb128  .LBB_END0_2-.LBB0_2          # BB_2 size
 505    .byte     0x0                          # BB_2 metadata (one successor)
 506   # BB record for BB_3
 507    .uleb128  3                            # BB_3 BB ID
 508    .uleb128  .LBB0_3-.LBB_END0_2          # BB_3 offset relative to the end of last block (BB_2).
 509    .uleb128  .LBB_END0_3-.LBB0_3          # BB_3 size
 510    .byte     0x0                          # BB_3 metadata (zero successors)
 511   # PGO Analysis Map
 512   .uleb128  1000                          # function entry count (only when enabled)
 513   # PGO data record for BB_0
 514    .uleb128  1000                         # BB_0 basic block frequency (only when enabled)
 515    .uleb128  3                            # BB_0 successors count (only enabled with branch probabilities)
 516    .uleb128  1                            # BB_0 successor 1 BB ID (only enabled with branch probabilities)
 517    .uleb128  0x22222222                   # BB_0 successor 1 branch probability (only enabled with branch probabilities)
 518    .uleb128  2                            # BB_0 successor 2 BB ID (only enabled with branch probabilities)
 519    .uleb128  0x33333333                   # BB_0 successor 2 branch probability (only enabled with branch probabilities)
 520    .uleb128  3                            # BB_0 successor 3 BB ID (only enabled with branch probabilities)
 521    .uleb128  0xaaaaaaaa                   # BB_0 successor 3 branch probability (only enabled with branch probabilities)
 522   # PGO data record for BB_1
 523    .uleb128  133                          # BB_1 basic block frequency (only when enabled)
 524    .uleb128  2                            # BB_1 successors count (only enabled with branch probabilities)
 525    .uleb128  2                            # BB_1 successor 1 BB ID (only enabled with branch probabilities)
 526    .uleb128  0x11111111                   # BB_1 successor 1 branch probability (only enabled with branch probabilities)
 527    .uleb128  3                            # BB_1 successor 2 BB ID (only enabled with branch probabilities)
 528    .uleb128  0x11111111                   # BB_1 successor 2 branch probability (only enabled with branch probabilities)
 529   # PGO data record for BB_2
 530    .uleb128  18                           # BB_2 basic block frequency (only when enabled)
 531    .uleb128  1                            # BB_2 successors count (only enabled with branch probabilities)
 532    .uleb128  3                            # BB_2 successor 1 BB ID (only enabled with branch probabilities)
 533    .uleb128  0xffffffff                   # BB_2 successor 1 branch probability (only enabled with branch probabilities)
 534   # PGO data record for BB_3
 535    .uleb128  1000                         # BB_3 basic block frequency (only when enabled)
 536    .uleb128  0                            # BB_3 successors count (only enabled with branch probabilities)
 537
 538 ``SHT_LLVM_OFFLOADING`` Section (offloading data)
 539 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 540 This section stores the binary data used to perform offloading device linking
 541 and execution, creating a fat binary. This section is emitted during compilation
 542 of offloading languages such as OpenMP or CUDA. If the data is intended to be
 543 used by the device linker only, it should use the ``SHF_EXCLUDE`` flag so it is
 544 automatically stripped from the final executable or shared library.
 545
 546 The binary data stored in this section conforms to a custom binary format used
 547 for storing offloading metadata. This format is effectively a string table
 548 containing metadata accompanied by a device image.
 549
 550 ``SHT_LLVM_LTO`` Section (LLVM bitcode for fat LTO)
 551 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 552 This section stores LLVM bitcode used to perform regular LTO or ThinLTO at link
 553 time. This section is generated when the compiler enables fat LTO. This section
 554 has the ``SHF_EXCLUDE`` flag so that it is stripped from the final executable
 555 or shared library.
 556
 557 CodeView-Dependent
 558 ------------------
 559
 560 ``.cv_file`` Directive
 561 ^^^^^^^^^^^^^^^^^^^^^^
 562 Syntax:
 563   ``.cv_file`` *FileNumber FileName* [ *checksum* ] [ *checksumkind* ]
 564
 565 ``.cv_func_id`` Directive
 566 ^^^^^^^^^^^^^^^^^^^^^^^^^
 567 Introduces a function ID that can be used with ``.cv_loc``.
 568
 569 Syntax:
 570   ``.cv_func_id`` *FunctionId*
 571
 572 ``.cv_inline_site_id`` Directive
 573 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 574 Introduces a function ID that can be used with ``.cv_loc``. Includes
 575 ``inlined at`` source location information for use in the line table of the
 576 caller, whether the caller is a real function or another inlined call site.
 577
 578 Syntax:
 579   ``.cv_inline_site_id`` *FunctionId* ``within`` *Function* ``inlined_at`` *FileNumber Line* [ *Column* ]
 580
 581 ``.cv_loc`` Directive
 582 ^^^^^^^^^^^^^^^^^^^^^
 583 The first number is a file number, must have been previously assigned with a
 584 ``.file`` directive, the second number is the line number and optionally the
 585 third number is a column position (zero if not specified).  The remaining
 586 optional items are ``.loc`` sub-directives.
 587
 588 Syntax:
 589   ``.cv_loc`` *FunctionId FileNumber* [ *Line* ] [ *Column* ] [ *prologue_end* ] [ ``is_stmt`` *value* ]
 590
 591 ``.cv_linetable`` Directive
 592 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 593 Syntax:
 594   ``.cv_linetable`` *FunctionId* ``,`` *FunctionStart* ``,`` *FunctionEnd*
 595
 596 ``.cv_inline_linetable`` Directive
 597 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 598 Syntax:
 599   ``.cv_inline_linetable`` *PrimaryFunctionId* ``,`` *FileNumber Line FunctionStart FunctionEnd*
 600
 601 ``.cv_def_range`` Directive
 602 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 603 The *GapStart* and *GapEnd* options may be repeated as needed.
 604
 605 Syntax:
 606   ``.cv_def_range`` *RangeStart RangeEnd* [ *GapStart GapEnd* ] ``,`` *bytes*
 607
 608 ``.cv_stringtable`` Directive
 609 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 610
 611 ``.cv_filechecksums`` Directive
 612 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 613
 614 ``.cv_filechecksumoffset`` Directive
 615 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 616 Syntax:
 617   ``.cv_filechecksumoffset`` *FileNumber*
 618
 619 ``.cv_fpo_data`` Directive
 620 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 621 Syntax:
 622   ``.cv_fpo_data`` *procsym*
 623
 624 Target Specific Behaviour
 625 =========================
 626
 627 X86
 628 ---
 629
 630 Relocations
 631 ^^^^^^^^^^^
 632
 633 **@ABS8** can be applied to symbols which appear as immediate operands to
 634 instructions that have an 8-bit immediate form for that operand. It causes
 635 the assembler to use the 8-bit form and an 8-bit relocation (e.g. ``R_386_8``
 636 or ``R_X86_64_8``) for the symbol.
 637
 638 For example:
 639
 640 .. code-block:: gas
 641
 642   cmpq $foo@ABS8, %rdi
 643
 644 This causes the assembler to select the form of the 64-bit ``cmpq`` instruction
 645 that takes an 8-bit immediate operand that is sign extended to 64 bits, as
 646 opposed to ``cmpq $foo, %rdi`` which takes a 32-bit immediate operand. This
 647 is also not the same as ``cmpb $foo, %dil``, which is an 8-bit comparison.
 648
 649
 650 **@GOTPCREL_NORELAX** can be used in place of ``@GOTPCREL`` to guarantee that
 651 the assembler emits an ``R_X86_64_GOTPCREL`` relocation instead of a relaxable
 652 ``R_X86_64[_REX]_GOTPCRELX`` relocation.
 653
 654 Windows on ARM
 655 --------------
 656
 657 Stack Probe Emission
 658 ^^^^^^^^^^^^^^^^^^^^
 659
 660 The reference implementation (Microsoft Visual Studio 2012) emits stack probes
 661 in the following fashion:
 662
 663 .. code-block:: gas
 664
 665   movw r4, #constant
 666   bl __chkstk
 667   sub.w sp, sp, r4
 668
 669 However, this has the limitation of 32 MiB (±16MiB).  In order to accommodate
 670 larger binaries, LLVM supports the use of ``-mcmodel=large`` to allow a 4GiB
 671 range via a slight deviation.  It will generate an indirect jump as follows:
 672
 673 .. code-block:: gas
 674
 675   movw r4, #constant
 676   movw r12, :lower16:__chkstk
 677   movt r12, :upper16:__chkstk
 678   blx r12
 679   sub.w sp, sp, r4
 680
 681 Variable Length Arrays
 682 ^^^^^^^^^^^^^^^^^^^^^^
 683
 684 The reference implementation (Microsoft Visual Studio 2012) does not permit the
 685 emission of Variable Length Arrays (VLAs).
 686
 687 The Windows ARM Itanium ABI extends the base ABI by adding support for emitting
 688 a dynamic stack allocation.  When emitting a variable stack allocation, a call
 689 to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup
 690 properly.  The emission of this stack probe emission is handled similar to the
 691 standard stack probe emission.
 692
 693 The MSVC environment does not emit code for VLAs currently.
 694
 695 Windows on ARM64
 696 ----------------
 697
 698 Stack Probe Emission
 699 ^^^^^^^^^^^^^^^^^^^^
 700
 701 The reference implementation (Microsoft Visual Studio 2017) emits stack probes
 702 in the following fashion:
 703
 704 .. code-block:: gas
 705
 706   mov x15, #constant
 707   bl __chkstk
 708   sub sp, sp, x15, lsl #4
 709
 710 However, this has the limitation of 256 MiB (±128MiB).  In order to accommodate
 711 larger binaries, LLVM supports the use of ``-mcmodel=large`` to allow a 8GiB
 712 (±4GiB) range via a slight deviation.  It will generate an indirect jump as
 713 follows:
 714
 715 .. code-block:: gas
 716
 717   mov x15, #constant
 718   adrp x16, __chkstk
 719   add x16, x16, :lo12:__chkstk
 720   blr x16
 721   sub sp, sp, x15, lsl #4
 722