X-Git-Url: http://plrg.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FExtensions.rst;h=c8ff07c2b0ca20fcbbfa117559e785be2e8828bc;hb=178fbb365428e16e1c73b0513f95a2bd374d79db;hp=78ff874abf096877799d3933555e1b4cc48c8ffb;hpb=80646283796b20c6a1b7d8eb69ce6f0478d54383;p=oota-llvm.git diff --git a/docs/Extensions.rst b/docs/Extensions.rst index 78ff874abf0..c8ff07c2b0c 100644 --- a/docs/Extensions.rst +++ b/docs/Extensions.rst @@ -14,6 +14,20 @@ Introduction This document describes extensions to tools and formats LLVM seeks compatibility with. +General Assembly Syntax +=========================== + +C99-style Hexadecimal Floating-point Constants +---------------------------------------------- + +LLVM's assemblers allow floating-point constants to be written in C99's +hexadecimal format instead of decimal if desired. + +.. code-block:: gas + + .section .data + .float 0x1c2.2ap3 + Machine-specific Assembly Syntax ================================ @@ -23,7 +37,7 @@ X86/COFF-Dependent Relocations ^^^^^^^^^^^ -The following additional relocation type is supported: +The following additional relocation types are supported: **@IMGREL** (AT&T syntax only) generates an image-relative relocation that corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or @@ -40,13 +54,29 @@ corresponds to the COFF relocation types ``IMAGE_REL_I386_DIR32NB`` (32-bit) or .long (fun@imgrel + 0x3F) .long $unwind$fun@imgrel +**.secrel32** generates a relocation that corresponds to the COFF relocation +types ``IMAGE_REL_I386_SECREL`` (32-bit) or ``IMAGE_REL_AMD64_SECREL`` (64-bit). + +**.secidx** relocation generates an index of the section that contains +the target. It corresponds to the COFF relocation types +``IMAGE_REL_I386_SECTION`` (32-bit) or ``IMAGE_REL_AMD64_SECTION`` (64-bit). + +.. code-block:: gas + + .section .debug$S,"rn" + .long 4 + .long 242 + .long 40 + .secrel32 _function_name + .secidx _function_name + ... ``.linkonce`` Directive ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Syntax: - ``.linkonce [ comdat type [ section identifier ] ]`` + ``.linkonce [ comdat type ]`` Supported COMDAT types: @@ -65,16 +95,6 @@ Supported COMDAT types: Duplicates are discarded, but the linker issues an error if any duplicates do not have exactly the same content. -``associative`` - Links the section if a certain other COMDAT section is linked. This other - section is indicated by its section identifier following the comdat type. - The following restrictions apply to the associated section: - - 1. It must be the name of a section already defined. - 2. It must differ from the current section. - 3. It must be a COMDAT section. - 4. It cannot be another associative COMDAT section. - ``largest`` Links the largest section from among the duplicates. @@ -88,6 +108,127 @@ Supported COMDAT types: .linkonce ... - .section .xdata$foo - .linkonce associative .text$foo - ... +``.section`` Directive +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +MC supports passing the information in ``.linkonce`` at the end of +``.section``. For example, these two codes are equivalent + +.. code-block:: gas + + .section secName, "dr", discard, "Symbol1" + .globl Symbol1 + Symbol1: + .long 1 + +.. code-block:: gas + + .section secName, "dr" + .linkonce discard + .globl Symbol1 + Symbol1: + .long 1 + +Note that in the combined form the COMDAT symbol is explicit. This +extension exists to support multiple sections with the same name in +different COMDATs: + + +.. code-block:: gas + + .section secName, "dr", discard, "Symbol1" + .globl Symbol1 + Symbol1: + .long 1 + + .section secName, "dr", discard, "Symbol2" + .globl Symbol2 + Symbol2: + .long 1 + +In addition to the types allowed with ``.linkonce``, ``.section`` also accepts +``associative``. The meaning is that the section is linked if a certain other +COMDAT section is linked. This other section is indicated by the comdat symbol +in this directive. It can be any symbol defined in the associated section, but +is 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 ``.foo`` +and ``.bar`` is associated to ``.foo``. + +.. code-block:: gas + + .section .foo,"bw",discard, "sym" + .section .bar,"rd",associative, "sym" + + +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 ``.seciton`` directive. +For example, the following code creates two sections named ``.text``. + +.. code-block:: gas + + .section .text,"ax",@progbits,unique,1 + nop + + .section .text,"ax",@progbits,unique,2 + nop + + +The unique number is not present in the resulting object at all. It is just used +in the assembler to differentiate the sections. + +Target Specific Behaviour +========================= + +Windows on ARM +-------------- + +Stack Probe Emission +^^^^^^^^^^^^^^^^^^^^ + +The reference implementation (Microsoft Visual Studio 2012) emits stack probes +in the following fashion: + +.. code-block:: gas + + movw r4, #constant + bl __chkstk + sub.w sp, sp, r4 + +However, this has the limitation of 32 MiB (±16MiB). In order to accommodate +larger binaries, LLVM supports the use of ``-mcode-model=large`` to allow a 4GiB +range via a slight deviation. It will generate an indirect jump as follows: + +.. code-block:: gas + + movw r4, #constant + movw r12, :lower16:__chkstk + movt r12, :upper16:__chkstk + blx r12 + sub.w sp, sp, r4 + +Variable Length Arrays +^^^^^^^^^^^^^^^^^^^^^^ + +The reference implementation (Microsoft Visual Studio 2012) does not permit the +emission of Variable Length Arrays (VLAs). + +The Windows ARM Itanium ABI extends the base ABI by adding support for emitting +a dynamic stack allocation. When emitting a variable stack allocation, a call +to ``__chkstk`` is emitted unconditionally to ensure that guard pages are setup +properly. The emission of this stack probe emission is handled similar to the +standard stack probe emission. + +The MSVC environment does not emit code for VLAs currently. +