0471e59358b856ebf6abda6aaf0226e045c36a67
[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 ('metadata ...' form).
62 data MetaExpr = MetaStr LMString
63 | MetaNode Int
64 | MetaVar LlvmVar
65 | MetaExpr [MetaExpr]
66 deriving (Eq)
67
68 -- | LLVM metadata nodes. See [Note: Metadata encoding].
69 data MetaVal
70 -- | A literal expression as a metadata value ('!{ ..}' form).
71 = MetaValExpr MetaExpr
72 -- | A metadata node as a metadata value ('!10' form).
73 | MetaValNode Int
74 deriving (Eq)
75
76 instance Show MetaExpr where
77 show (MetaStr s ) = "metadata !\"" ++ unpackFS s ++ "\""
78 show (MetaNode n ) = "metadata !" ++ show n
79 show (MetaVar v ) = show v
80 show (MetaExpr es) = intercalate ", " $ map show es
81
82 instance Show MetaVal where
83 show (MetaValExpr e) = "!{ " ++ show e ++ "}"
84 show (MetaValNode n) = "!" ++ show n
85
86 -- | Associated some metadata with a specific label for attaching to an
87 -- instruction.
88 type MetaData = (LMString, MetaVal)
89
90 -- | Metadata declarations. Metadata can only be declared in global scope.
91 data MetaDecl
92 -- | Named metadata. Only used for communicating module information to
93 -- LLVM. ('!name = !{ [!<n>] }' form).
94 = MetaNamed LMString [Int]
95 -- | Metadata node declaration.
96 -- ('!0 = metadata !{ <metadata expression> }' form).
97 | MetaUnamed Int MetaExpr
98
99 -- | LLVM function call arguments.
100 data MetaArgs
101 = ArgVar LlvmVar -- ^ Regular LLVM variable as argument.
102 | ArgMeta MetaExpr -- ^ Metadata as argument.
103 deriving (Eq)
104
105 instance Show MetaArgs where
106 show (ArgVar v) = show v
107 show (ArgMeta m) = show m
108
109 {-
110 Note: Metadata encoding
111 ~~~~~~~~~~~~~~~~~~~~~~~
112 The encoding use today has some redundancy in the form of 'MetaValNode'.
113 Instead of the current encoding where MetaExpr is an independent recursive
114 type, the encoding below could be used where MetaExpr and MetaVal are
115 co-recursive. The current encoding was chosen instead as it appears easier
116 to work with and cleaner to separate the two types.
117
118 -- metadata ...
119 data MetaExpr = MetaStr String
120 | MetaVar LlvmVar
121 | MetaVal [MetaVal]
122
123 -- !{ .. } | !10
124 data MetaVal = MetaExpr MetaExpr
125 | MetaNode Int
126 -}
127