mirrors/llvm-project
0
0
Fork 0
mirror of https://github.com/llvm/llvm-project.git synced 2025-04-16 12:06:36 +00:00
Code Issues Projects Releases Wiki Activity

[DebugInfo] Update SourceLevelDebugging.rst to better explain kill locations

Browse Source 
Reviewed By: scott.linder, jryans

Differential Revision: https://reviews.llvm.org/D140989
This commit is contained in:
OCHyams 2023-04-26 10:27:40 +01:00
parent c604a2c2c0
commit a93c423971
1 changed files with 22 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
llvm/docs/SourceLevelDebugging.rst
View File

@ -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