[PATCH] D59790: [DebugInfo][Docs] Document how variable location metadata is transformed through target codegen

[Jeremy Morse via Phabricator via llvm-commits]

jmorse created this revision.
jmorse added reviewers: aprantl, bjope, vsk, probinson, dstenb, rnk.
Herald added subscribers: llvm-commits, jdoerfert.
Herald added a project: LLVM.

This patch adds documentation to SourceLevelDebugging.rst that explains how variable location information is compiled from the IR representation down to the end of the codegen pipeline, but avoiding discussion of file formats and encoding.

As far as I'm aware this is all currently undocumented (in html docs at least). There may be much better ways of structuring the added information, and I'm very happy to reorganize/rewrite the text.

Things that I believe this documents:

- How llvm.dbg.value intrinsics map down onto DBG_VALUE instructions
- Several examples of how variable locations should be changed when instruction scheduling moves instructions
- What LiveDebugVariables does
- What LiveDebugValues does
- The rationale behind _why_ LiveDebugValues expands variable location information at a late stage, versus mem2reg encoding lots of information
- The fact that DBG_VALUE changes meaning (I believe!) after LiveDebugValues
- That each block must define all valid variable locations in it by the end of codegen (see discussion in D59431 <https://reviews.llvm.org/D59431>)

What it doesn't explain, and is still a mystery to me:

- _Why_ does LiveDebugVariables do what it does?

I'd also be highly interested in things that are currently uncertain/unknown, but really should be documented. Ideally this page should contain all the rationale behind how debuginfo is designed/operates.


Repository:
  rL LLVM

https://reviews.llvm.org/D59790

Files:
  docs/SourceLevelDebugging.rst

-------------- next part --------------
A non-text attachment was scrubbed...
Name: D59790.192178.patch
Type: text/x-patch
Size: 15086 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20190325/64bb06c9/attachment.bin>