@@ -143,6 +143,42 @@ debugging information influences optimization passes then it will be reported
143
143
as a failure. See :doc: `TestingGuide ` for more information on LLVM test
144
144
infrastructure and how to run various tests.
145
145
146
+ .. _variables_and_variable_fragments :
147
+
148
+ Variables and Variable Fragments
149
+ ================================
150
+
151
+ In this document "variable" refers generally to any source language object
152
+ which can have a value, including at least:
153
+
154
+ - Variables
155
+ - Constants
156
+ - Formal parameters
157
+
158
+ .. note ::
159
+
160
+ There is no special provision for "true" constants in LLVM today, and
161
+ they are instead treated as local or global variables.
162
+
163
+ A variable is represented by a `local variable <LangRef.html#dilocalvariable >`_
164
+ or `global variable <LangRef.html#diglobalvariable >`_ metadata node.
165
+
166
+ A "variable fragment" (or just "fragment") is a contiguous span of bits of a
167
+ variable.
168
+
169
+ A :ref: `debug record <debug_records >` which refers to a ``DIExpression `` ending
170
+ with a ``DW_OP_LLVM_fragment `` operation describes a fragment of the variable
171
+ it refers to.
172
+
173
+ The operands of the ``DW_OP_LLVM_fragment `` operation encode the bit offset of
174
+ the fragment relative to the start of the variable, and the size of the
175
+ fragment in bits, respectively.
176
+
177
+ .. note ::
178
+
179
+ The ``DW_OP_LLVM_fragment `` operation acts only to encode the fragment
180
+ information, and does not have an effect on the semantics of the expression.
181
+
146
182
.. _format :
147
183
148
184
Debugging information format
@@ -510,10 +546,23 @@ values through compilation, when objects are promoted to SSA values a
510
546
``#dbg_value `` record is created for each assignment, recording the
511
547
variable's new location. Compared with the ``#dbg_declare `` record:
512
548
513
- * A #dbg_value terminates the effect of any preceding #dbg_values for (any
514
- overlapping fragments of) the specified variable.
515
- * The #dbg_value's position in the IR defines where in the instruction stream
516
- the variable's value changes.
549
+ * A ``#dbg_value `` terminates the effects that any preceding records have on
550
+ any common bits of a common variable.
551
+
552
+ .. note ::
553
+
554
+ The current implementation generally terminates the effect of every
555
+ record in its entirety if any of its effects would be terminated, rather
556
+ than carrying forward the effect of previous records for non-overlapping
557
+ bits as it would be permitted to do by this definition. This is allowed
558
+ just as dropping any debug information at any point in the compilation is
559
+ allowed.
560
+
561
+ One exception to this is :doc: `AssignmentTracking ` where certain
562
+ memory-based locations are carried forward partially in some situations.
563
+
564
+ * The ``#dbg_value ``'s position in the IR defines where in the instruction
565
+ stream the variable's value changes.
517
566
* Operands can be constants, indicating the variable is assigned a
518
567
constant value.
519
568
0 commit comments