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

[StephenTozer]

Minor comments but otherwise LGTM.

llvm/docs/SourceLevelDebugging.rst

520

534–535

Maybe a minor point, but "in practice" implies it is valid but just doesn't occur naturally, when it would really just be an error however it came about. Maybe "this cannot appear as part of a !DIArgList" or something similar.

536–537

Technically the DIExpression doesn't have to be empty - it just has to be non-complex, i.e. it contains only DW_OP_LLVM_tag_offset or DW_OP_LLVM_fragment elements. The distinction probably isn't important here however.

[jryans]

Thanks for adding these docs, looks great to me! 🙂 It will be helpful for the future to have these details recorded.

[scott.linder]

LGTM (with the other comments resolved), thank you for documenting this!

[Orlando]

Thanks everyone for reviewing this (and the rest of the stack), sorry it has taken a while to get these landed!

llvm/docs/SourceLevelDebugging.rst

 developer by the debugger should not show a state that would never have existed
 in the execution of the unoptimized program, given the same input. Doing so
 risks 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.
 
 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
 remaining information.
 
 To illustrate some potential issues, consider the following example:
 
 .. code-block:: llvm
entry:
     %toret = add i32 %plusten, %g
     call @llvm.dbg.value(metadata i32 %toret, metadata !1, metadata !2)
     ret i32 %toret
   }
 
 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
 
   define i32 @foo(i32 %bar, i1 %cond) {
   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
     %toret = add i32 %plusten, %g
     call @llvm.dbg.value(metadata i32 %toret, metadata !1, metadata !2)
     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
 ============================================================
 
 LLVM preserves debug information throughout mid-level and backend passes,
 ultimately producing a mapping between source-level information and
 instruction ranges. This