Skip to content

Commit c9910d5

Browse files
authored
[LangRef] Clarify definition of fragments (#145582)
Try to give a more complete description of what we call a "fragment", and how debug records interact when fragments are involved.
1 parent 096cad5 commit c9910d5

File tree

1 file changed

+53
-4
lines changed

1 file changed

+53
-4
lines changed

llvm/docs/SourceLevelDebugging.rst

Lines changed: 53 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,42 @@ debugging information influences optimization passes then it will be reported
143143
as a failure. See :doc:`TestingGuide` for more information on LLVM test
144144
infrastructure and how to run various tests.
145145

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+
146182
.. _format:
147183

148184
Debugging information format
@@ -510,10 +546,23 @@ values through compilation, when objects are promoted to SSA values a
510546
``#dbg_value`` record is created for each assignment, recording the
511547
variable's new location. Compared with the ``#dbg_declare`` record:
512548

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.
517566
* Operands can be constants, indicating the variable is assigned a
518567
constant value.
519568

0 commit comments

Comments
 (0)