[PATCH] D29110: LangRef: Document the allowed metadata dropping transforms.

[Peter Collingbourne via Phabricator via llvm-commits]

pcc created this revision.

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


https://reviews.llvm.org/D29110

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -3941,15 +3941,27 @@
 
     %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
+
+It is valid for a pass to drop metadata if it is attached to an instruction,
+but metadata attached to a module using named metadata may not be dropped,
+and metadata attached to a function or a global variable may only be dropped
+if the function or global variable is itself dropped. However, debug metadata
+(named metadata with the name ``!llvm.dbg.*``, or metadata attachments with
+identifier ``!dbg``) may always be dropped.
+
 More information about specific metadata nodes recognized by the
 optimizers and code generator is found below.
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D29110.85674.patch
Type: text/x-patch
Size: 1355 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20170125/6fa944fd/attachment.bin>