[llvm] a2247d4 - [LangRef] Describe linkage types, allocation size of declarations for global variables

[Eli Friedman via llvm-commits]

Author: Matthias Schiffer
Date: 2020-05-08T16:21:30-07:00
New Revision: a2247d42e46c7740545c6289701d41fe19ba469a

URL: https://github.com/llvm/llvm-project/commit/a2247d42e46c7740545c6289701d41fe19ba469a
DIFF: https://github.com/llvm/llvm-project/commit/a2247d42e46c7740545c6289701d41fe19ba469a.diff

LOG: [LangRef] Describe linkage types, allocation size of declarations for global variables

Linkage type was only referenced for functions, not for global
variables.

Clarify that LLVM doesn't make assumption about the allocation size when
no definitive initializer for a global variable is known.

Differential Revision: https://reviews.llvm.org/D78952

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index fdec9ceaa9c9..001d3ed7ac6d 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -272,8 +272,8 @@ linkage:
     visible, meaning that it participates in linkage and can be used to
     resolve external symbol references.
 
-It is illegal for a function *declaration* to have any linkage type
-other than ``external`` or ``extern_weak``.
+It is illegal for a global variable or function *declaration* to have any
+linkage type other than ``external`` or ``extern_weak``.
 
 .. _callingconv:
 
@@ -615,6 +615,8 @@ Global variable definitions must be initialized.
 Global variables in other translation units can also be declared, in which
 case they don't have an initializer.
 
+Global variables can optionally specify a :ref:`linkage type <linkage>`.
+
 Either global variable definitions or declarations may have an explicit section
 to be placed in and may have an optional explicit alignment specified. If there
 is a mismatch between the explicit or inferred section information for the
@@ -686,6 +688,13 @@ assume that the globals are densely packed in their section and try to
 iterate over them as an array, alignment padding would break this
 iteration. The maximum alignment is ``1 << 29``.
 
+For global variables declarations, as well as definitions that may be
+replaced at link time (``linkonce``, ``weak``, ``extern_weak`` and ``common``
+linkage types), LLVM makes no assumptions about the allocation size of the
+variables, except that they may not overlap. The alignment of a global variable
+declaration or replaceable definition must not be greater than the alignment of
+the definition it resolves to.
+
 Globals can also have a :ref:`DLL storage class <dllstorageclass>`,
 an optional :ref:`runtime preemption specifier <runtime_preemption_model>`,
 an optional :ref:`global attributes <glattrs>` and