From 83efd3d61d61d9189a37278bde806807bb85f639 Mon Sep 17 00:00:00 2001 From: Peter Collingbourne Date: Wed, 25 Jan 2017 21:50:14 +0000 Subject: [PATCH] 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 llvm-svn: 293101 --- docs/LangRef.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docs/LangRef.rst b/docs/LangRef.rst index ba15713429f..ecf48455427 100644 --- a/docs/LangRef.rst +++ b/docs/LangRef.rst @@ -3941,15 +3941,28 @@ to the ``add`` instruction using the ``!dbg`` identifier: %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.