llvm.org GIT mirror llvm / 0b5f8d1
Write 3.6 metadata release notes git-svn-id: https://llvm.org/svn/llvm-project/llvm/branches/release_36@226212 91177308-0d34-0410-b5e6-96231b3b80d8 Duncan P. N. Exon Smith 4 years ago
1 changed file(s) with 182 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
101101 .. _discussions: http://lists.cs.uiuc.edu/pipermail/llvmdev/2014-May/073235.html
102102
103103
104 Metadata is not a Value
105 -----------------------
106
107 Metadata nodes (``!{...}``) and strings (``!"..."``) are no longer values.
108 They have no use-lists, no type, cannot RAUW, and cannot be function-local.
109
110 Bridges between Value and Metadata
111 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
112
113 LLVM intrinsics can reference metadata using the ``metadata`` type, and
114 metadata nodes can reference constant values.
115
116 Function-local metadata is limited to direct arguments to LLVM intrinsics.
117
118 Metadata is typeless
119 ^^^^^^^^^^^^^^^^^^^^
120
121 The following old IR:
122
123 .. code-block:: llvm
124
125 @g = global i32 0
126
127 define void @foo(i32 %v) {
128 entry:
129 call void @llvm.md(metadata !{i32 %v})
130 call void @llvm.md(metadata !{i32* @global})
131 call void @llvm.md(metadata !0)
132 call void @llvm.md(metadata !{metadata !"string"})
133 call void @llvm.md(metadata !{metadata !{metadata !1, metadata !"string"}})
134 ret void, !bar !1, !baz !2
135 }
136
137 declare void @llvm.md(metadata)
138
139 !0 = metadata !{metadata !1, metadata !2, metadata !3, metadata !"some string"}
140 !1 = metadata !{metadata !2, null, metadata !"other", i32* @global, i32 7}
141 !2 = metadata !{}
142
143 is should now be written as:
144
145 .. code-block:: llvm
146
147 @g = global i32 0
148
149 define void @foo(i32 %v) {
150 entry:
151 call void @llvm.md(metadata i32 %v) ; The only legal place for function-local
152 ; metadata.
153 call void @llvm.md(metadata i32* @global)
154 call void @llvm.md(metadata !0)
155 call void @llvm.md(metadata !{!"string"})
156 call void @llvm.md(metadata !{!{!1, !"string"}})
157 ret void, !bar !1, !baz !2
158 }
159
160 declare void @llvm.md(metadata)
161
162 !0 = !{!1, !2, !3, !"some string"}
163 !1 = !{!2, null, !"other", i32* @global, i32 7}
164 !2 = !{}
165
166 Distinct metadata nodes
167 ^^^^^^^^^^^^^^^^^^^^^^^
168
169 Metadata nodes can opt-out of uniquing, using the keyword ``distinct``.
170 Distinct nodes are still owned by the context, but are stored in a side table,
171 and not uniqued.
172
173 In LLVM 3.5, metadata nodes would drop uniquing if an operand changed to
174 ``null`` during optimizations. This is no longer true. However, if an operand
175 change causes a uniquing collision, they become ``distinct``. Unlike LLVM 3.5,
176 where serializing to assembly or bitcode would re-unique the nodes, they now
177 remain ``distinct``.
178
179 The following IR:
180
181 .. code-block:: llvm
182
183 !named = !{!0, !1, !2, !3, !4, !5, !6, !7, !8}
184
185 !0 = !{}
186 !1 = !{}
187 !2 = distinct !{}
188 !3 = distinct !{}
189 !4 = !{!0}
190 !5 = distinct !{!0}
191 !6 = !{!4, !{}, !5}
192 !7 = !{!{!0}, !0, !5}
193 !8 = distinct !{!{!0}, !0, !5}
194
195 is equivalent to the following:
196
197 .. code-block:: llvm
198
199 !named = !{!0, !0, !1, !2, !3, !4, !5, !5, !6}
200
201 !0 = !{}
202 !1 = distinct !{}
203 !2 = distinct !{}
204 !3 = !{!0}
205 !4 = distinct !{!0}
206 !5 = !{!3, !0, !4}
207 !6 = distinct !{!3, !0, !4}
208
209 Constructing cyclic graphs
210 ^^^^^^^^^^^^^^^^^^^^^^^^^^
211
212 During graph construction, if a metadata node transitively references a forward
213 declaration, the node itself is considered "unresolved" until the forward
214 declaration resolves. An unresolved node can RAUW itself to support uniquing.
215 Nodes automatically resolve once all their operands have resolved.
216
217 However, cyclic graphs prevent the nodes from resolving. An API client that
218 constructs a cyclic graph must call ``resolveCycles()`` to resolve nodes in the
219 cycle.
220
221 To save self-references from that burden, self-referencing nodes are implicitly
222 ``distinct``. So the following IR:
223
224 .. code-block:: llvm
225
226 !named = !{!0, !1, !2, !3, !4}
227
228 !0 = !{!0}
229 !1 = !{!1}
230 !2 = !{!2, !1}
231 !3 = !{!2, !1}
232 !4 = !{!2, !1}
233
234 is equivalent to:
235
236 .. code-block:: llvm
237
238 !named = !{!0, !1, !2, !3, !3}
239
240 !0 = distinct !{!0}
241 !1 = distinct !{!1}
242 !2 = distinct !{!2, !1}
243 !3 = !{!2, !1}
244
245 MDLocation (aka DebugLoc aka DILocation)
246 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
247
248 There's a new first-class metadata construct called ``MDLocation`` (to be
249 followed in subsequent releases by others). It's used for the locations
250 referenced by ``!dbg`` metadata attachments.
251
252 For example, if an old ``!dbg`` attachment looked like this:
253
254 .. code-block:: llvm
255
256 define i32 @foo(i32 %a, i32 %b) {
257 entry:
258 %add = add i32 %a, %b, !dbg !0
259 ret %add, !dbg !1
260 }
261
262 !0 = metadata !{i32 10, i32 3, metadata !2, metadata !1)
263 !1 = metadata !{i32 20, i32 7, metadata !3)
264 !2 = metadata !{...}
265 !3 = metadata !{...}
266
267 the new attachment looks like this:
268
269 .. code-block:: llvm
270
271 define i32 @foo(i32 %a, i32 %b) {
272 entry:
273 %add = add i32 %a, %b, !dbg !0
274 ret %add, !dbg !1
275 }
276
277 !0 = !MDLocation(line: 10, column: 3, scope: !2, inlinedAt: !1)
278 !1 = !MDLocation(line: 20, column: 7, scope: !3)
279 !2 = !{...}
280 !3 = !{...}
281
282 The fields are named, can be reordered, and have sane defaults if left out
283 (although ``scope:`` is required).
284
285
104286 Changes to the ARM Backend
105287 --------------------------
106288