[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.
diff --git a/llvm/docs/SourceLevelDebugging.rst b/llvm/docs/SourceLevelDebugging.rst
index 8a11dcf..dfc8c53e 100644
--- a/llvm/docs/SourceLevelDebugging.rst
+++ b/llvm/docs/SourceLevelDebugging.rst
@@ -143,6 +143,42 @@
as a failure. See :doc:`TestingGuide` for more information on LLVM test
infrastructure and how to run various tests.
+.. _variables_and_variable_fragments:
+
+Variables and Variable Fragments
+================================
+
+In this document "variable" refers generally to any source language object
+which can have a value, including at least:
+
+- Variables
+- Constants
+- Formal parameters
+
+.. note::
+
+ There is no special provision for "true" constants in LLVM today, and
+ they are instead treated as local or global variables.
+
+A variable is represented by a `local variable <LangRef.html#dilocalvariable>`_
+or `global variable <LangRef.html#diglobalvariable>`_ metadata node.
+
+A "variable fragment" (or just "fragment") is a contiguous span of bits of a
+variable.
+
+A :ref:`debug record <debug_records>` which refers to a ``DIExpression`` ending
+with a ``DW_OP_LLVM_fragment`` operation describes a fragment of the variable
+it refers to.
+
+The operands of the ``DW_OP_LLVM_fragment`` operation encode the bit offset of
+the fragment relative to the start of the variable, and the size of the
+fragment in bits, respectively.
+
+.. note::
+
+ The ``DW_OP_LLVM_fragment`` operation acts only to encode the fragment
+ information, and does not have an effect on the semantics of the expression.
+
.. _format:
Debugging information format
@@ -510,10 +546,23 @@
``#dbg_value`` record is created for each assignment, recording the
variable's new location. Compared with the ``#dbg_declare`` record:
-* A #dbg_value terminates the effect of any preceding #dbg_values for (any
- overlapping fragments of) the specified variable.
-* The #dbg_value's position in the IR defines where in the instruction stream
- the variable's value changes.
+* A ``#dbg_value`` terminates the effects that any preceding records have on
+ any common bits of a common variable.
+
+ .. note::
+
+ The current implementation generally terminates the effect of every
+ record in its entirety if any of its effects would be terminated, rather
+ than carrying forward the effect of previous records for non-overlapping
+ bits as it would be permitted to do by this definition. This is allowed
+ just as dropping any debug information at any point in the compilation is
+ allowed.
+
+ One exception to this is :doc:`AssignmentTracking` where certain
+ memory-based locations are carried forward partially in some situations.
+
+* The ``#dbg_value``'s position in the IR defines where in the instruction
+ stream the variable's value changes.
* Operands can be constants, indicating the variable is assigned a
constant value.
