[llvm] r293101 - LangRef: Document the allowed metadata dropping transforms.

[Peter Collingbourne via llvm-commits]

Author: pcc
Date: Wed Jan 25 15:50:14 2017
New Revision: 293101

URL: http://llvm.org/viewvc/llvm-project?rev=293101&view=rev
Log:
LangRef: Document the allowed metadata dropping transforms.

Document the current practice regarding dropping metadata on modules,
functions and global variables.

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

Modified:
    llvm/trunk/docs/LangRef.rst

Modified: llvm/trunk/docs/LangRef.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LangRef.rst?rev=293101&r1=293100&r2=293101&view=diff
==============================================================================
--- llvm/trunk/docs/LangRef.rst (original)
+++ llvm/trunk/docs/LangRef.rst Wed Jan 25 15:50:14 2017
@@ -3941,15 +3941,28 @@ to the ``add`` instruction using the ``!
 
     %indvar.next = add i64 %indvar, 1, !dbg !21
 
-Metadata can also be attached to a function definition. Here metadata ``!22``
-is attached to the ``foo`` function using the ``!dbg`` identifier:
+Metadata can also be attached to a function or a global variable. Here metadata
+``!22`` is attached to the ``f1`` and ``f2 functions, and the globals ``g1``
+and ``g2`` using the ``!dbg`` identifier:
 
 .. code-block:: llvm
 
-    define void @foo() !dbg !22 {
+    declare !dbg !22 void @f1()
+    define void @f2() !dbg !22 {
       ret void
     }
 
+    @g1 = global i32 0, !dbg !22
+    @g2 = external global i32, !dbg !22
+
+A transformation is required to drop any metadata attachment that it does not
+know or know it can't preserve. Currently there is an exception for metadata
+attachment to globals for ``!type`` and ``!absolute_symbol`` which can't be
+unconditionally dropped unless the global is itself deleted.
+
+Metadata attached to a module using named metadata may not be dropped, with
+the exception of debug metadata (named metadata with the name ``!llvm.dbg.*``).
+
 More information about specific metadata nodes recognized by the
 optimizers and code generator is found below.