828 lines · plain
1===============2LLVM Extensions3===============4 5.. contents::6 :local:7 8.. toctree::9 :hidden:10 11Introduction12============13 14This document describes extensions to tools and formats LLVM seeks compatibility15with.16 17General Assembly Syntax18===========================19 20C99-style Hexadecimal Floating-point Constants21----------------------------------------------22 23LLVM's assemblers allow floating-point constants to be written in C99's24hexadecimal format instead of decimal if desired.25 26.. code-block:: gas27 28 .section .data29 .float 0x1c2.2ap330 31Machine-specific Assembly Syntax32================================33 34X86/COFF-Dependent35------------------36 37Relocations38^^^^^^^^^^^39 40The following additional relocation types are supported:41 42**@IMGREL** (AT&T syntax only) generates an image-relative relocation that43corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or44``IMAGE_REL_AMD64_ADDR32NB`` (64-bit).45 46.. code-block:: text47 48 .text49 fun:50 mov foo@IMGREL(%ebx, %ecx, 4), %eax51 52 .section .pdata53 .long fun@IMGREL54 .long (fun@imgrel + 0x3F)55 .long $unwind$fun@imgrel56 57**.secrel32** generates a relocation that corresponds to the COFF relocation58types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit).59 60**.secidx** relocation generates an index of the section that contains61the target. It corresponds to the COFF relocation types62``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit).63 64.. code-block:: none65 66 .section .debug$S,"rn"67 .long 468 .long 24269 .long 4070 .secrel32 _function_name + 071 .secidx _function_name72 ...73 74``.linkonce`` Directive75^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^76 77Syntax:78 79 ``.linkonce [ comdat type ]``80 81Supported COMDAT types:82 83``discard``84 Discards duplicate sections with the same COMDAT symbol. This is the default85 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 have92 different sizes.93 94``same_contents``95 Duplicates are discarded, but the linker issues an error if any duplicates96 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:: gas106 107 .section .text$foo108 .linkonce109 ...110 111``.section`` Directive112^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^113 114MC supports passing the information in ``.linkonce`` at the end of115``.section``. For example, these two codes are equivalent116 117.. code-block:: gas118 119 .section secName, "dr", discard, "Symbol1"120 .globl Symbol1121 Symbol1:122 .long 1123 124.. code-block:: gas125 126 .section secName, "dr"127 .linkonce discard128 .globl Symbol1129 Symbol1:130 .long 1131 132Note that in the combined form the COMDAT symbol is explicit. This133extension exists to support multiple sections with the same name in134different COMDATs:135 136 137.. code-block:: gas138 139 .section secName, "dr", discard, "Symbol1"140 .globl Symbol1141 Symbol1:142 .long 1143 144 .section secName, "dr", discard, "Symbol2"145 .globl Symbol2146 Symbol2:147 .long 1148 149In addition to the types allowed with ``.linkonce``, ``.section`` also accepts150``associative``. The meaning is that the section is linked if a certain other151COMDAT section is linked. This other section is indicated by the comdat symbol152in this directive. It can be any symbol defined in the associated section, but153is 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 160In the following example, the symbol ``sym`` is the comdat symbol of ``.foo``,161and ``.bar`` is associated with ``.foo``.162 163.. code-block:: gas164 165 .section .foo,"bw",discard, "sym"166 .section .bar,"rd",associative, "sym"167 168MC 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-only174 - ``s``: Shared section175 - ``w``: Writable176 - ``x``: Executable section177 - ``y``: Not readable178 - ``D``: Discardable (``IMAGE_SCN_MEM_DISCARDABLE``)179 180These flags are all compatible with GNU as, with the exception of the ``D`` flag,181which GNU as does not support. For compatibility with GNU as, sections with a name182starting with ``.debug`` are implicitly discardable.183 184 185ARM64/COFF-Dependent186--------------------187 188Relocations189^^^^^^^^^^^190 191The following additional symbol variants are supported:192 193**:secrel_lo12:** generates a relocation that corresponds to the COFF relocation194types ``IMAGE_REL_ARM64_SECREL_LOW12A`` or ``IMAGE_REL_ARM64_SECREL_LOW12L``.195 196**:secrel_hi12:** generates a relocation that corresponds to the COFF relocation197type ``IMAGE_REL_ARM64_SECREL_HIGH12A``.198 199.. code-block:: gas200 201 add x0, x0, :secrel_hi12:symbol202 ldr x0, [x0, :secrel_lo12:symbol]203 204 add x1, x1, :secrel_hi12:symbol205 add x1, x1, :secrel_lo12:symbol206 ...207 208 209ELF-Dependent210-------------211 212``.section`` Directive213^^^^^^^^^^^^^^^^^^^^^^214 215In order to support creating multiple sections with the same name and comdat,216it is possible to add a unique number at the end of the ``.section`` directive.217For example, the following code creates two sections named ``.text``.218 219.. code-block:: gas220 221 .section .text,"ax",@progbits,unique,1222 nop223 224 .section .text,"ax",@progbits,unique,2225 nop226 227 228The unique number is not present in the resulting object at all. It is just used229in the assembler to differentiate the sections.230 231The 'o' flag is mapped to ``SHF_LINK_ORDER``. If it is present, a symbol232must be given that identifies the section to be placed in the233``.sh_link``.234 235.. code-block:: gas236 237 .section .foo,"a",@progbits238 .Ltmp:239 .section .bar,"ao",@progbits,.Ltmp240 241which is equivalent to:242 243.. code-block:: gas244 245 .section .foo,"a",@progbits246 .section .bar,"ao",@progbits,.foo247 248``.linker-options`` Section (linker options)249^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^250 251In order to support passing linker options from the frontend to the linker, a252special section of type ``SHT_LLVM_LINKER_OPTIONS`` (usually named253``.linker-options`` though the name is not significant as it is identified by254the type). The contents of this section are a simple pair-wise encoding of255directives for consideration by the linker. The strings are encoded as standard256null-terminated UTF-8 strings. They are emitted inline to avoid having the257linker traverse the object file for retrieving the value. The linker is258permitted to not honour the option and instead provide a warning/error to the259user that the requested option was not honoured.260 261The section has type ``SHT_LLVM_LINKER_OPTIONS`` and has the ``SHF_EXCLUDE``262flag to ensure that the section is treated as opaque by linkers which do not263support the feature and will not be emitted into the final linked binary.264 265This would be equivalent to the following raw assembly:266 267.. code-block:: gas268 269 .section ".linker-options","e",@llvm_linker_options270 .asciz "option 1"271 .asciz "value 1"272 .asciz "option 2"273 .asciz "value 2"274 275The following directives are specified:276 277 - ``lib``278 279 The parameter identifies a library to be linked against. The library will280 be looked up in the default and any specified library search paths281 (specified to this point).282 283 - ``libpath``284 285 The parameter identifies an additional library search path to be considered286 when looking up libraries after the inclusion of this option.287 288``SHT_LLVM_DEPENDENT_LIBRARIES`` Section (Dependent Libraries)289^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^290 291This section contains strings specifying libraries to be added to the link by292the linker.293 294The section should be consumed by the linker and not written to the output.295 296The strings are encoded as standard null-terminated UTF-8 strings.297 298For example:299 300.. code-block:: gas301 302 .section ".deplibs","MS",@llvm_dependent_libraries,1303 .asciz "library specifier 1"304 .asciz "library specifier 2"305 306The interpretation of the library specifiers is defined by the consuming linker.307 308``SHT_LLVM_CALL_GRAPH_PROFILE`` Section (Call Graph Profile)309^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^310 311This section is used to pass a call graph profile to the linker which can be312used to optimize the placement of sections. It contains a sequence of313(from symbol, to symbol, weight) tuples.314 315It shall have a type of ``SHT_LLVM_CALL_GRAPH_PROFILE`` (0x6fff4c02), shall316have the ``SHF_EXCLUDE`` flag set, the ``sh_link`` member shall hold the section317header index of the associated symbol table, and shall have a ``sh_entsize`` of31816. It should be named ``.llvm.call-graph-profile``.319 320The contents of the section shall be a sequence of ``Elf_CGProfile`` entries.321 322.. code-block:: c323 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 339This is represented in assembly as:340 341.. code-block:: gas342 343 .cg_profile from, to, 42344 345``.cg_profile`` directives are processed at the end of the file. It is an error346if either ``from`` or ``to`` are undefined temporary symbols. If either symbol347is a temporary symbol, then the section symbol is used instead. If either348symbol is undefined, then that symbol is defined as if ``.weak symbol`` has been349written at the end of the file. This forces the symbol to show up in the symbol350table.351 352``SHT_LLVM_ADDRSIG`` Section (address-significance table)353^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^354 355This section is used to mark symbols as address-significant, i.e., the address356of the symbol is used in a comparison or leaks outside the translation unit. It357has the same meaning as the absence of the LLVM attributes ``unnamed_addr``358and ``local_unnamed_addr``.359 360Any sections referred to by symbols that are not marked as address-significant361in any object file may be safely merged by a linker without breaking the362address uniqueness guarantee provided by the C and C++ language standards.363 364The contents of the section are a sequence of ULEB128-encoded integers365referring to the symbol table indexes of the address-significant symbols.366 367There are two associated assembly directives:368 369.. code-block:: gas370 371 .addrsig372 373This instructs the assembler to emit an address-significance table. Without374this directive, all symbols are considered address-significant.375 376.. code-block:: gas377 378 .addrsig_sym sym379 380If ``sym`` is not otherwise referenced or defined anywhere else in the file,381this directive is a no-op. Otherwise, mark ``sym`` as address-significant.382 383``SHT_LLVM_SYMPART`` Section (symbol partition specification)384^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^385 386This section is used to mark symbols with the `partition`_ that they387belong to. An ``.llvm_sympart`` section consists of a null-terminated string388specifying the name of the partition followed by a relocation referring to389the symbol that belongs to the partition. It may be constructed as follows:390 391.. code-block:: gas392 393 .section ".llvm_sympart","",@llvm_sympart394 .asciz "libpartition.so"395 .word symbol_in_partition396 397.. _partition: https://lld.llvm.org/Partitions.html398 399``SHT_LLVM_BB_ADDR_MAP`` Section (basic block address map)400^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^401This section stores the binary addresses of basic blocks along with other related402metadata. This information can be used to map binary profiles (like perf403profiles) directly to machine basic blocks.404This section is emitted with ``-basic-block-address-map`` and will contain405a BB address map table for every function.406 407The ``SHT_LLVM_BB_ADDR_MAP`` type provides backward compatibility to allow408reading older versions of the BB address map generated by older compilers (up to409two years old). Each function entry starts with a version byte which specifies410the encoding version to use. This is followed by a feature byte which specifies411the features specific to this particular entry. The function base address is412stored as a full address. Other addresses in the entry (block begin and end413addresses and callsite end addresses) are stored in a running-offset fashion,414as offsets relative to prior addresses.415 416The following versioning schemes are currently supported (newer versions support417features of the older versions).418 419Version 4 (newest): Capable of encoding basic block hashes. This feature is420enabled by the 7th bit of the feature byte.421 422Example:423 424.. code-block:: gas425 426 .section ".llvm_bb_addr_map","",@llvm_bb_addr_map427 .byte 4 # version number428 .byte 96 # feature byte429 .quad .Lfunc_begin0 # address of the function430 .byte 2 # number of basic blocks431 # BB record for BB_0432 .byte 0 # BB_0 ID433 .uleb128 .Lfunc_begin0-.Lfunc_begin0 # BB_0 offset relative to function entry (always zero)434 .byte 0 # number of callsites in this block435 .uleb128 .LBB_END0_0-.Lfunc_begin0 # BB_0 size436 .byte x # BB_0 metadata437 .quad 9080480745856761856 # BB_0 hash438 # BB record for BB_1439 .byte 1 # BB_1 ID440 .uleb128 .LBB0_1-.LBB_END0_0 # BB_1 offset relative to the end of last block (BB_0).441 .byte 2 # number of callsites in this block442 .uleb128 .LBB0_1_CS0-.LBB0_1 # offset of callsite end relative to the previous offset (.LBB0_1)443 .uleb128 .LBB0_1_CS1-.LBB0_1_CS0 # offset of callsite end relative to the previous offset (.LBB0_1_CS0)444 .uleb128 .LBB_END0_1-.LBB0_1_CS1 # BB_1 size offset (Offset of the block end relative to the previous offset).445 .byte y # BB_1 metadata446 .quad 2363478788702666771 # BB_1 hash447 448Version 3: Capable of encoding callsite offsets. Enabled by the 6th bit449of the feature byte.450 451Example:452 453.. code-block:: gas454 455 .section ".llvm_bb_addr_map","",@llvm_bb_addr_map456 .byte 3 # version number457 .byte 32 # feature byte458 .quad .Lfunc_begin0 # address of the function459 .byte 2 # number of basic blocks460 # BB record for BB_0461 .byte 0 # BB_0 ID462 .uleb128 .Lfunc_begin0-.Lfunc_begin0 # BB_0 offset relative to function entry (always zero)463 .byte 0 # number of callsites in this block464 .uleb128 .LBB_END0_0-.Lfunc_begin0 # BB_0 size465 .byte x # BB_0 metadata466 # BB record for BB_1467 .byte 1 # BB_1 ID468 .uleb128 .LBB0_1-.LBB_END0_0 # BB_1 offset relative to the end of last block (BB_0).469 .byte 2 # number of callsites in this block470 .uleb128 .LBB0_1_CS0-.LBB0_1 # offset of callsite end relative to the previous offset (.LBB0_1)471 .uleb128 .LBB0_1_CS1-.LBB0_1_CS0 # offset of callsite end relative to the previous offset (.LBB0_1_CS0)472 .uleb128 .LBB_END0_1-.LBB0_1_CS1 # BB_1 size offset (Offset of the block end relative to the previous offset).473 .byte y # BB_1 metadata474 475Version 2: Capable of encoding split functions. Enabled by the 4th bit of the476feature byte. The base address of each split range is stored as a full address.477The first range corresponds to the function entry.478 479Example:480 481.. code-block:: gas482 483 .section ".llvm_bb_addr_map","",@llvm_bb_addr_map484 .byte 2 # version number485 .byte 8 # feature byte486 .byte 2 # number of basic block ranges487 # 1st BB range (corresponding to the function entry)488 .quad .Lfunc_begin0 # base address489 .byte 1 # number of basic blocks in this range490 # BB record for BB_0491 .byte 0 # BB_0 ID492 .uleb128 .Lfunc_begin0-.Lfunc_begin0 # BB_0 offset relative to function entry (always zero)493 .uleb128 .LBB_END0_0-.Lfunc_begin0 # BB_0 size494 .byte x # BB_0 metadata495 # 2nd BB range496 .quad func.part.1497 .byte 1 # number of basic blocks in this range498 # BB record for BB_1499 .byte 1 # BB_1 ID500 .uleb128 func.part.1-func.part.1 # BB_1 offset relative to the range begin (always zero)501 .uleb128 .LBB_END0_1-func.part.1 # BB_1 size502 .byte 1 # BB_1 metadata503 504PGO Analysis Map505""""""""""""""""506 507PGO related analysis data can be emitted after each function within the508``SHT_LLVM_BB_ADDR_MAP`` through the optional ``pgo-analysis-map`` flag.509Supported analyses currently are Function Entry Count, Basic Block Frequencies,510and Branch Probabilities.511 512Each analysis is enabled or disabled via a bit in the feature byte. Currently,513those bits are:514 515#. Function Entry Count - Number of times the function was called as taken516 from a PGO profile. This will always be zero if PGO was not used or the517 function was not encountered in the profile.518 519#. Basic Block Frequencies - Encoded as raw block frequency value taken from520 MBFI analysis. This value is an integer that encodes the relative frequency521 compared to the entry block. More information can be found in522 ``llvm/Support/BlockFrequency.h``.523 524#. Branch Probabilities - Encoded as raw numerator for branch probability525 taken from MBPI analysis. This value is the numerator for a fixed point ratio526 defined in ``llvm/Support/BranchProbability.h``. It indicates the probability527 that the block is followed by a given successor block during execution.528 529This extra data requires version 2 or above. This is necessary since successors530of basic blocks won't know their index but will know their BB ID.531 532Example of BBAddrMap with PGO data:533 534.. code-block:: gas535 536 .section ".llvm_bb_addr_map","",@llvm_bb_addr_map537 .byte 2 # version number538 .byte 7 # feature byte - PGO analyses enabled mask539 .quad .Lfunc_begin0 # address of the function540 .uleb128 4 # number of basic blocks541 # BB record for BB_0542 .uleb128 0 # BB_0 BB ID543 .uleb128 .Lfunc_begin0-.Lfunc_begin0 # BB_0 offset relative to function entry (always zero)544 .uleb128 .LBB_END0_0-.Lfunc_begin0 # BB_0 size545 .byte 0x18 # BB_0 metadata (multiple successors)546 # BB record for BB_1547 .uleb128 1 # BB_1 BB ID548 .uleb128 .LBB0_1-.LBB_END0_0 # BB_1 offset relative to the end of last block (BB_0).549 .uleb128 .LBB_END0_1-.LBB0_1 # BB_1 size550 .byte 0x0 # BB_1 metadata (two successors)551 # BB record for BB_2552 .uleb128 2 # BB_2 BB ID553 .uleb128 .LBB0_2-.LBB_END1_0 # BB_2 offset relative to the end of last block (BB_1).554 .uleb128 .LBB_END0_2-.LBB0_2 # BB_2 size555 .byte 0x0 # BB_2 metadata (one successor)556 # BB record for BB_3557 .uleb128 3 # BB_3 BB ID558 .uleb128 .LBB0_3-.LBB_END0_2 # BB_3 offset relative to the end of last block (BB_2).559 .uleb128 .LBB_END0_3-.LBB0_3 # BB_3 size560 .byte 0x0 # BB_3 metadata (zero successors)561 # PGO Analysis Map562 .uleb128 1000 # function entry count (only when enabled)563 # PGO data record for BB_0564 .uleb128 1000 # BB_0 basic block frequency (only when enabled)565 .uleb128 3 # BB_0 successors count (only enabled with branch probabilities)566 .uleb128 1 # BB_0 successor 1 BB ID (only enabled with branch probabilities)567 .uleb128 0x22222222 # BB_0 successor 1 branch probability (only enabled with branch probabilities)568 .uleb128 2 # BB_0 successor 2 BB ID (only enabled with branch probabilities)569 .uleb128 0x33333333 # BB_0 successor 2 branch probability (only enabled with branch probabilities)570 .uleb128 3 # BB_0 successor 3 BB ID (only enabled with branch probabilities)571 .uleb128 0xaaaaaaaa # BB_0 successor 3 branch probability (only enabled with branch probabilities)572 # PGO data record for BB_1573 .uleb128 133 # BB_1 basic block frequency (only when enabled)574 .uleb128 2 # BB_1 successors count (only enabled with branch probabilities)575 .uleb128 2 # BB_1 successor 1 BB ID (only enabled with branch probabilities)576 .uleb128 0x11111111 # BB_1 successor 1 branch probability (only enabled with branch probabilities)577 .uleb128 3 # BB_1 successor 2 BB ID (only enabled with branch probabilities)578 .uleb128 0x11111111 # BB_1 successor 2 branch probability (only enabled with branch probabilities)579 # PGO data record for BB_2580 .uleb128 18 # BB_2 basic block frequency (only when enabled)581 .uleb128 1 # BB_2 successors count (only enabled with branch probabilities)582 .uleb128 3 # BB_2 successor 1 BB ID (only enabled with branch probabilities)583 .uleb128 0xffffffff # BB_2 successor 1 branch probability (only enabled with branch probabilities)584 # PGO data record for BB_3585 .uleb128 1000 # BB_3 basic block frequency (only when enabled)586 .uleb128 0 # BB_3 successors count (only enabled with branch probabilities)587 588``SHT_LLVM_OFFLOADING`` Section (offloading data)589^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^590This section stores the binary data used to perform offloading device linking591and execution, creating a fat binary. This section is emitted during compilation592of offloading languages such as OpenMP or CUDA. If the data is intended to be593used by the device linker only, it should use the ``SHF_EXCLUDE`` flag so it is594automatically stripped from the final executable or shared library.595 596The binary data stored in this section conforms to a custom binary format used597for storing offloading metadata. This format is effectively a string table598containing metadata accompanied by a device image.599 600``SHT_LLVM_LTO`` Section (LLVM bitcode for fat LTO)601^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^602This section stores LLVM bitcode used to perform regular LTO or ThinLTO at link603time. This section is generated when the compiler enables fat LTO. This section604has the ``SHF_EXCLUDE`` flag so that it is stripped from the final executable605or shared library.606 607``SHT_LLVM_JT_SIZES`` Section (Jump table addresses and sizes)608^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^609This section stores pairs of (jump table address, number of entries).610This information is useful for tools that need to statically reconstruct611the control flow of executables.612 613``SHT_LLVM_CFI_JUMP_TABLE`` Section (CFI jump table)614^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^615This section contains the instructions that make up a `CFI jump table`_.616It is expected to be ``SHF_ALLOC`` and may be laid out like a normal617section. The ``SHT_LLVM_CFI_JUMP_TABLE`` section type gives the linker618permission to modify the section in ways that would not normally be619permitted, in order to optimize calls via the jump table.620 621Each ``sh_entsize`` sized slice of a section of this type containing622exactly one relocation may be considered to be a jump table entry623that branches to the target of the relocation. This allows the linker624to replace the jump table entry with the function body if it is small625enough, or if the function is the last function in the jump table.626 627A section of this type does not have to be placed according to its628name. The linker may place the section in whichever output section it629sees fit (generally the section that would provide the best locality).630 631.. _CFI jump table: https://clang.llvm.org/docs/ControlFlowIntegrityDesign.html#forward-edge-cfi-for-indirect-function-calls632 633``SHT_LLVM_CALL_GRAPH`` Section (Call Graph)634^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^635 636This section is used to store the call graph. It has a type of637``SHT_LLVM_CALL_GRAPH`` (0x6fff4c0f). Details of call graph section layout638are described in :doc:`CallGraphSection`.639 640For example:641 642.. code-block:: gas643 644 .section ".llvm.callgraph","",@llvm_call_graph645 .byte 0646 .byte 7647 .quad .Lball648 .quad 0649 .byte 3650 .quad foo651 .quad bar652 .quad baz653 .byte 3654 .quad 4524972987496481828655 .quad 3498816979441845844656 .quad 8646233951371320954657 658This indicates that ``ball`` calls ``foo``, ``bar`` and ``baz`` directly;659``ball`` indirectly calls functions whose types are ``4524972987496481828``,660``3498816979441845844`` and ``8646233951371320954``.661 662CodeView-Dependent663------------------664 665``.cv_file`` Directive666^^^^^^^^^^^^^^^^^^^^^^667Syntax:668 ``.cv_file`` *FileNumber FileName* [ *checksum* ] [ *checksumkind* ]669 670``.cv_func_id`` Directive671^^^^^^^^^^^^^^^^^^^^^^^^^672Introduces a function ID that can be used with ``.cv_loc``.673 674Syntax:675 ``.cv_func_id`` *FunctionId*676 677``.cv_inline_site_id`` Directive678^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^679Introduces a function ID that can be used with ``.cv_loc``. Includes680``inlined at`` source location information for use in the line table of the681caller, whether the caller is a real function or another inlined call site.682 683Syntax:684 ``.cv_inline_site_id`` *FunctionId* ``within`` *Function* ``inlined_at`` *FileNumber Line* [ *Column* ]685 686``.cv_loc`` Directive687^^^^^^^^^^^^^^^^^^^^^688The first number is a file number, which must have been previously assigned with a689``.file`` directive. The second number is the line number, and the690optional third number is a column position (zero if not specified). The remaining691optional items are ``.loc`` sub-directives.692 693Syntax:694 ``.cv_loc`` *FunctionId FileNumber* [ *Line* ] [ *Column* ] [ *prologue_end* ] [ ``is_stmt`` *value* ]695 696``.cv_linetable`` Directive697^^^^^^^^^^^^^^^^^^^^^^^^^^^698Syntax:699 ``.cv_linetable`` *FunctionId* ``,`` *FunctionStart* ``,`` *FunctionEnd*700 701``.cv_inline_linetable`` Directive702^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^703Syntax:704 ``.cv_inline_linetable`` *PrimaryFunctionId* ``,`` *FileNumber Line FunctionStart FunctionEnd*705 706``.cv_def_range`` Directive707^^^^^^^^^^^^^^^^^^^^^^^^^^^708The *GapStart* and *GapEnd* options may be repeated as needed.709 710Syntax:711 ``.cv_def_range`` *RangeStart RangeEnd* [ *GapStart GapEnd* ] ``,`` *bytes*712 713``.cv_stringtable`` Directive714^^^^^^^^^^^^^^^^^^^^^^^^^^^^^715 716``.cv_filechecksums`` Directive717^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^718 719``.cv_filechecksumoffset`` Directive720^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^721Syntax:722 ``.cv_filechecksumoffset`` *FileNumber*723 724``.cv_fpo_data`` Directive725^^^^^^^^^^^^^^^^^^^^^^^^^^726Syntax:727 ``.cv_fpo_data`` *procsym*728 729Target-Specific Behaviour730=========================731 732X86733---734 735Relocations736^^^^^^^^^^^737 738**@ABS8** can be applied to symbols which appear as immediate operands to739instructions that have an 8-bit immediate form for that operand. It causes740the assembler to use the 8-bit form and an 8-bit relocation (e.g. ``R_386_8``741or ``R_X86_64_8``) for the symbol.742 743For example:744 745.. code-block:: gas746 747 cmpq $foo@ABS8, %rdi748 749This causes the assembler to select the form of the 64-bit ``cmpq`` instruction750that takes an 8-bit immediate operand that is sign extended to 64 bits, as751opposed to ``cmpq $foo, %rdi`` which takes a 32-bit immediate operand. This752is also not the same as ``cmpb $foo, %dil``, which is an 8-bit comparison.753 754 755**@GOTPCREL_NORELAX** can be used in place of ``@GOTPCREL`` to guarantee that756the assembler emits an ``R_X86_64_GOTPCREL`` relocation instead of a relaxable757``R_X86_64[_REX]_GOTPCRELX`` relocation.758 759Windows on ARM760--------------761 762Stack Probe Emission763^^^^^^^^^^^^^^^^^^^^764 765The reference implementation (Microsoft Visual Studio 2012) emits stack probes766in the following fashion:767 768.. code-block:: gas769 770 movw r4, #constant771 bl __chkstk772 sub.w sp, sp, r4773 774However, this has the limitation of 32 MiB (±16MiB). In order to accommodate775larger binaries, LLVM supports the use of ``-mcmodel=large`` to allow a 4GiB776range via a slight deviation. It will generate an indirect jump as follows:777 778.. code-block:: gas779 780 movw r4, #constant781 movw r12, :lower16:__chkstk782 movt r12, :upper16:__chkstk783 blx r12784 sub.w sp, sp, r4785 786Variable Length Arrays787^^^^^^^^^^^^^^^^^^^^^^788 789The reference implementation (Microsoft Visual Studio 2012) does not permit the790emission of Variable Length Arrays (VLAs).791 792The Windows ARM Itanium ABI extends the base ABI by adding support for emitting793a dynamic stack allocation. When emitting a variable stack allocation, a call794to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup795properly. The emission of this stack probe emission is handled similarly to the796standard stack probe emission.797 798The MSVC environment does not emit code for VLAs currently.799 800Windows on ARM64801----------------802 803Stack Probe Emission804^^^^^^^^^^^^^^^^^^^^805 806The reference implementation (Microsoft Visual Studio 2017) emits stack probes807in the following fashion:808 809.. code-block:: gas810 811 mov x15, #constant812 bl __chkstk813 sub sp, sp, x15, lsl #4814 815However, this has the limitation of 256 MiB (±128MiB). In order to accommodate816larger binaries, LLVM supports the use of ``-mcmodel=large`` to allow an 8GiB817(±4GiB) range via a slight deviation. It will generate an indirect jump as818follows:819 820.. code-block:: gas821 822 mov x15, #constant823 adrp x16, __chkstk824 add x16, x16, :lo12:__chkstk825 blr x16826 sub sp, sp, x15, lsl #4827 828