Iteration on dterei's metadata design
[ghc.git] / compiler / llvmGen / Llvm / MetaData.hs
1 --------------------------------------------------------------------------------
2 -- | The LLVM Metadata System.
3 --
4 -- The LLVM metadata feature is poorly documented but roughly follows the
5 -- following design:
6 -- * Metadata can be constructed in a few different ways (See below).
7 -- * After which it can either be attached to LLVM statements to pass along
8 -- extra information to the optimizer and code generator OR specificially named
9 -- metadata has an affect on the whole module (i.e., linking behaviour).
10 --
11 --
12 -- # Constructing metadata
13 -- Metadata comes largely in three forms:
14 --
15 -- * Metadata expressions -- these are the raw metadata values that encode
16 -- information. They consist of metadata strings, metadata nodes, regular
17 -- LLVM values (both literals and references to global variables) and
18 -- metadata expressions (i.e., recursive data type). Some examples:
19 -- !{ metadata !"hello", metadata !0, i32 0 }
20 -- !{ metadata !1, metadata !{ i32 0 } }
21 --
22 -- * Metadata nodes -- global metadata variables that attach a metadata
23 -- expression to a number. For example:
24 -- !0 = metadata !{ [<metadata expressions>] !}
25 --
26 -- * Named metadata -- global metadata variables that attach a metadata nodes
27 -- to a name. Used ONLY to communicated module level information to LLVM
28 -- through a meaningful name. For example:
29 -- !llvm.module.linkage = !{ !0, !1 }
30 --
31 --
32 -- # Using Metadata
33 -- Using metadata depends on the form it is in:
34 --
35 -- * Attach to instructions -- metadata can be attached to LLVM instructions
36 -- using a specific reference as follows:
37 -- %l = load i32* @glob, !nontemporal !10
38 -- %m = load i32* @glob, !nontemporal !{ i32 0, metadata !{ i32 0 } }
39 -- Only metadata nodes or expressions can be attached, named metadata cannot.
40 -- Refer to LLVM documentation for which instructions take metadata and its
41 -- meaning.
42 --
43 -- * As arguments -- llvm functions can take metadata as arguments, for
44 -- example:
45 -- call void @llvm.dbg.value(metadata !{ i32 0 }, i64 0, metadata !1)
46 -- As with instructions, only metadata nodes or expressions can be attached.
47 --
48 -- * As a named metadata -- Here the metadata is simply declared in global
49 -- scope using a specific name to communicate module level information to LLVM.
50 -- For example:
51 -- !llvm.module.linkage = !{ !0, !1 }
52 --
53 module Llvm.MetaData where
54
55 import Data.List (intercalate)
56
57 import Llvm.Types
58
59 import FastString
60
61 -- | LLVM metadata expressions
62 data MetaExpr = MetaStr LMString
63 | MetaNode Int
64 | MetaVar LlvmVar
65 | MetaStruct [MetaExpr]
66 deriving (Eq)
67
68 instance Show MetaExpr where
69 show (MetaStr s ) = "metadata !\"" ++ unpackFS s ++ "\""
70 show (MetaNode n ) = "metadata !" ++ show n
71 show (MetaVar v ) = show v
72 show (MetaStruct es) = "metadata !{ " ++ intercalate ", " (map show es) ++ "}"
73
74 -- | Associates some metadata with a specific label for attaching to an
75 -- instruction.
76 data MetaAnnot = MetaAnnot LMString MetaExpr
77 deriving (Eq)
78
79 -- | Metadata declarations. Metadata can only be declared in global scope.
80 data MetaDecl
81 -- | Named metadata. Only used for communicating module information to
82 -- LLVM. ('!name = !{ [!<n>] }' form).
83 = MetaNamed LMString [Int]
84 -- | Metadata node declaration.
85 -- ('!0 = metadata !{ <metadata expression> }' form).
86 | MetaUnamed Int MetaExpr