[docs] Improvements to CMake.rst

[oota-llvm.git] / docs / Extensions.rst

diff --git a/docs/Extensions.rst b/docs/Extensions.rst
index 9dddab5b5ed9663a6d5a5e4a68ae29bc111a8463..c8ff07c2b0ca20fcbbfa117559e785be2e8828bc 100644 (file)
--- a/docs/Extensions.rst
+++ b/docs/Extensions.rst
@@ -76,7 +76,7 @@ the target.  It corresponds to the COFF relocation types
 
 Syntax:
 
-   ``.linkonce [ comdat type [ section identifier ] ]``
+   ``.linkonce [ comdat type ]``
 
 Supported COMDAT types:
 
@@ -95,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.
 
@@ -118,10 +108,6 @@ Supported COMDAT types:
   .linkonce
     ...
 
-  .section .xdata$foo
-  .linkonce associative .text$foo
-    ...
-
 ``.section`` Directive
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -160,6 +146,48 @@ different COMDATs:
   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
 =========================
 
@@ -178,7 +206,7 @@ in the following fashion:
   bl __chkstk
   sub.w sp, sp, r4
 
-However, this has the limitation of 32 MiB (±16MiB).  In order to accomodate
+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:
 
@@ -190,3 +218,17 @@ range via a slight deviation.  It will generate an indirect jump as follows:
   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.
+