[llvm] a93c423 - [DebugInfo] Update SourceLevelDebugging.rst to better explain kill locations
via llvm-commits
llvm-commits at lists.llvm.org
Wed Apr 26 02:32:51 PDT 2023
Author: OCHyams
Date: 2023-04-26T10:31:54+01:00
New Revision: a93c4239719382e5b17335f3452e9095937ed6b7
URL: https://github.com/llvm/llvm-project/commit/a93c4239719382e5b17335f3452e9095937ed6b7
DIFF: https://github.com/llvm/llvm-project/commit/a93c4239719382e5b17335f3452e9095937ed6b7.diff
LOG: [DebugInfo] Update SourceLevelDebugging.rst to better explain kill locations
Reviewed By: scott.linder, jryans
Differential Revision: https://reviews.llvm.org/D140989
Added:
Modified:
llvm/docs/SourceLevelDebugging.rst
Removed:
################################################################################
diff --git a/llvm/docs/SourceLevelDebugging.rst b/llvm/docs/SourceLevelDebugging.rst
index be288f6f7f172..e2416040d7dd7 100644
--- a/llvm/docs/SourceLevelDebugging.rst
+++ b/llvm/docs/SourceLevelDebugging.rst
@@ -436,7 +436,7 @@ trust in the debugger.
Sometimes perfectly preserving variable locations is not possible, often when a
redundant calculation is optimized out. In such cases, a ``llvm.dbg.value``
-with operand ``undef`` should be used, to terminate earlier variable locations
+with operand ``poison`` should be used, to terminate earlier variable locations
and let the debugger present ``optimized out`` to the developer. Withholding
these potentially stale variable values from the developer diminishes the
amount of available debug information, but increases the reliability of the
@@ -508,7 +508,7 @@ might consider this placement of dbg.values:
However, this will cause ``!3`` to have the return value of ``@gazonk()`` at
the same time as ``!1`` has the constant value zero -- a pair of assignments
that never occurred in the unoptimized program. To avoid this, we must terminate
-the range that ``!1`` has the constant value assignment by inserting an undef
+the range that ``!1`` has the constant value assignment by inserting a poison
dbg.value before the dbg.value for ``!3``:
.. code-block:: llvm
@@ -517,7 +517,7 @@ dbg.value before the dbg.value for ``!3``:
entry:
call @llvm.dbg.value(metadata i32 0, metadata !1, metadata !2)
%g = call i32 @gazonk()
- call @llvm.dbg.value(metadata i32 undef, metadata !1, metadata !2)
+ call @llvm.dbg.value(metadata i32 poison, metadata !1, metadata !2)
call @llvm.dbg.value(metadata i32 %g, metadata !3, metadata !2)
%addoper = select i1 %cond, i32 11, i32 12
%plusten = add i32 %bar, %addoper
@@ -526,9 +526,26 @@ dbg.value before the dbg.value for ``!3``:
ret i32 %toret
}
+There are a few other dbg.value configurations that mean it terminates
+dominating location definitions without adding a new location. The complete
+list is:
+
+* Any location operand is ``poison`` (or ``undef``).
+* Any location operand is an empty metadata tuple (``!{}``) (which cannot
+ occur in ``!DIArgList``s).
+* There are no location operands (empty ``DIArgList``) and the ``DIExpression``
+ is empty.
+
+This class of dbg.value that kills variable locations is called a "kill
+dbg.value" or "kill location", and for legacy reasons the term "undef
+dbg.value" may be used in existing code. The ``DbgVariableIntrinsic`` methods
+``isKillLocation`` and ``setKillLocation`` should be used where possible rather
+than inspecting location operands directly to check or set whether a dbg.value
+is a kill location.
+
In general, if any dbg.value has its operand optimized out and cannot be
-recovered, then an undef dbg.value is necessary to terminate earlier variable
-locations. Additional undef dbg.values may be necessary when the debugger can
+recovered, then a kill dbg.value is necessary to terminate earlier variable
+locations. Additional kill dbg.values may be necessary when the debugger can
observe re-ordering of assignments.
How variable location metadata is transformed during CodeGen
More information about the llvm-commits
mailing list