[PATCH] D58726: [DebugInfo][Docs] Explicitly document how dbg.value intrinsics are interpreted in optimized code

[Adrian Prantl via Phabricator via llvm-commits]

aprantl added a comment.

Thanks! Small nitpicks inside.



================
Comment at: docs/SourceLevelDebugging.rst:401
+memory store to the variables position on the stack. However in heavily
+optimized code LLVM promotes most variables into SSA registers, which can
+eventually be placed in physical registers or memory locations. To track SSA
----------------
`SSA values`


================
Comment at: docs/SourceLevelDebugging.rst:403
+eventually be placed in physical registers or memory locations. To track SSA
+registers through compilation, when objects are promoted to SSA registers an
+``llvm.dbg.value`` intrinsic is created for each assignment, recording the
----------------
values ...


================
Comment at: docs/SourceLevelDebugging.rst:408
+* A dbg.value invalidates the location of any earlier dbg.values for the
+  specified variable.
+* The dbg.value's position in the IR defines where in the instruction stream
----------------
`for (any overlapping fragments of) the`


================
Comment at: docs/SourceLevelDebugging.rst:419
+
+As a result, optimization passes must take care when dbg.value intrinsics are
+altered or moved -- the developer will observe such changes reflected in
----------------
``` ``llvm.dbg.value`` ```


================
Comment at: docs/SourceLevelDebugging.rst:426
+misleading the developer by reporting a state that does not exist, damaging
+their understanding of the optimized program.
+
----------------
and undermining their trust in the debugger.


================
Comment at: docs/SourceLevelDebugging.rst:429
+Sometimes perfectly preserving variable locations is not possible, often
+when a redundant calculation is optimized out. In such cases, a dbg.value with
+operand ``undef`` should be used, to terminate earlier variable locations and
----------------
ditto


================
Comment at: docs/SourceLevelDebugging.rst:430
+when a redundant calculation is optimized out. In such cases, a dbg.value with
+operand ``undef`` should be used, to terminate earlier variable locations and
+present ``optimized out`` to the developer. Witholding these potentially stale
----------------
... and let the debugger present ...


Repository:
  rL LLVM

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D58726/new/

https://reviews.llvm.org/D58726