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

[NeoRaider]

Summary

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.

[NeoRaider]

Related issue: https://bugs.llvm.org/show_bug.cgi?id=45681

[efriedma]

I don't want to take this too far off track, but there are some additional caveats which might not be obvious to someone reading this rule:

1. Global variables are not allowed to overlap. (This follows from the pointer aliasing rules.)
2. The alignment does have to match the declared alignment. And the "declared" alignment is implicitly computed based on the type if it isn't explicitly specified.

Not sure if it makes sense to modify the language here.

llvm/docs/LangRef.rst

691

Not sure the italics are necessary.

[NeoRaider]

In D78952#2006342, @efriedma wrote:

1. Global variables are not allowed to overlap. (This follows from the pointer aliasing rules.)

Makes sense, I'll add this.

2. The alignment does have to match the declared alignment. And the "declared" alignment is implicitly computed based on the type if it isn't explicitly specified.

Question regarding alignment: I would expect that a variable declaration with lower alignment than the definition it refers to should be fine. For example, when declaring an extern global variable of a forward-declared struct type in C, clang will use an opaque type with alignment 1 for the declaration.

[spatel]

llvm/docs/LangRef.rst

693

Vocabulary nit: the LangRef has mostly avoided legalese to remain readable and approachable even for non-native English speakers, so I'd reduce this to something like:
"...LLVM makes no assumptions about the allocation sizes of the variables."

[efriedma]

Question regarding alignment: I would expect that a variable declaration with lower alignment than the definition it refers to should be fine. For example, when declaring an extern global variable of a forward-declared struct type in C, clang will use an opaque type with alignment 1 for the declaration.

Sure, the alignment specified on a declaration can be lower than the alignment on the definition.

[NeoRaider]

• Changed wording as suggested by review
• Mention overlap
• Mention alignment

[efriedma]

LGTM

[NeoRaider]

Is there something left for me to do to have this change applied?

[efriedma]

I'll commit it for you. How should I credit you on the git "Author" line?

[NeoRaider]

Author: Matthias Schiffer <[e-mail]>

[nikic]

In getPointerDereferenceableBytes(), we currently assume that non-extern_weak globals are dereferenceable up to their type store size: https://github.com/llvm/llvm-project/blob/2153544865a9733b06579823814c981f735e4201/llvm/lib/IR/Value.cpp#L907

In ConstantFoldGetElementPtr(), we currently assume that GEPs without notional overindexing are inbounds of non-extern_weak globals: https://github.com/llvm/llvm-project/blob/2153544865a9733b06579823814c981f735e4201/llvm/lib/IR/ConstantFold.cpp#L2283 (Note that this code is broken for other reasons, it's missing a pointee type check -- this is why I'm looking into this in the first place.)

In getObjectSize() we do check for a definitive initializer: https://github.com/llvm/llvm-project/blob/a6f66d57e1d626a9b676f6e3ec0e084bdca3a934/llvm/lib/Analysis/MemoryBuiltins.cpp#L821

So I wanted to double check what the intended semantics here are. For a global without definitive initializer, do we assume that the global is *at least* as large as the value type, or do we allow it to be smaller? If the latter, then we need to fix our dereferencability assumptions.

[nikic]

I've put up D142970 as an incomplete patch to remove the dereferencability assumption. Not sure this is a good idea.

llvm/docs/LangRef.rst

``linkonce_odr``, ``weak_odr``
     ``linkonce_odr`` and ``weak_odr`` linkage types to indicate that the
     global will only be merged with equivalent globals. These linkage
     types are otherwise the same as their non-``odr`` versions.
 ``external``
     If none of the above identifiers are used, the global is externally
     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:
 
 Calling Conventions
 -------------------
 
 LLVM :ref:`functions <functionstructure>`, :ref:`calls <i_call>` and
 :ref:`invokes <i_invoke>` can all have an optional calling convention

 Global variables define regions of memory allocated at compilation time
 instead of run-time.
 
 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
 variable declaration and its definition the resulting behavior is undefined.
 
 A variable may be defined as a global ``constant``, which indicates that
 the contents of the variable will **never** be modified (enabling better
 optimization, allowing the global data to be placed in the read-only

 convenient. If an explicit alignment is specified, the global is forced
 to have exactly that alignment. Targets and optimizers are not allowed
 to over-align the global if the global has an assigned section. In this
 case, the extra alignment could be observable: for example, code could
 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
 an optional list of attached :ref:`metadata <metadata>`.
 
 Variables and aliases can have a
 :ref:`Thread Local Storage Model <tls_model>`.