RFC on discourse:
https://discourse.llvm.org/t/rfc-debug-info-for-coroutine-suspension-locations-take-2/86606
With this commit, we add `DILabel` debug infos to the resume points of a
coroutine. Those labels can be used by debugging scripts to figure out
the exact line and column at which a coroutine was suspended by looking
up current `__coro_index` value inside the coroutines frame, and then
searching for the corresponding label inside the coroutine's resume
function.
The DWARF information generated for such a label looks like:
```
0x00000f71: DW_TAG_label
DW_AT_name ("__coro_resume_1")
DW_AT_decl_file ("generator-example.cpp")
DW_AT_decl_line (5)
DW_AT_decl_column (3)
DW_AT_artificial (true)
DW_AT_LLVM_coro_suspend_idx (0x01)
DW_AT_low_pc (0x00000000000019be)
```
The labels can be mapped to their corresponding `__coro_idx` values
either via their naming convention `__coro_resume_<N>` or using the new
`DW_AT_LLVM_coro_suspend_idx` attribute. In gdb, those line numebrs can
be looked up using `info line -function my_coroutine -label
__coro_resume_1`. LLDB unfortunately does not understand DW_TAG_label
debug information, yet.
Given this is an artificial compiler-generated label, I did apply the
DW_AT_artificial tag to it. The DWARFv5 standard only allows that tag on
type and variable definitions, but this is a natural extension and was
also blessed in the RFC on discourse.
Also, this commit adds `DW_AT_decl_column` to labels, not only for
coroutines but also for normal C and C++ labels. While not strictly
necessary, I am doing so now because it would be harder to do so later
without breaking the binary LLVM-IR format
Drive-by fixes: While reading the existing test cases to understand how
to write my own test case, I did a couple of small typo fixes and
comment improvements
This commit is a major overhaul of the documentation on debugging C++
coroutines with the following goals:
* Make it more accessible to casual C++ programmers, i.e. non-toolchain
developers. Move the low-level details around ABI further down, and
instead start with real-life examples and copy-paste-friendly code,
first.
* Cover LLDB in addition to GCC. Provide copy-pasteable scripts for LLDB
and not only GCC.
* Cover additional topics, such as:
* single-stepping into a coroutine
* using `__builtin_return_address` for tracking suspension points
(inspired by Folly's blog series on coroutine debugging)
* Document LLDB's support for devirtualization of
`std::coroutine_handle`, both from an end user perspective as well as
its internal implementation
from PEP8
(https://peps.python.org/pep-0008/#programming-recommendations):
> Comparisons to singletons like None should always be done with is or
is not, never the equality operators.
Co-authored-by: Eisuke Kawashima <e-kwsm@users.noreply.github.com>
Previously when I wrote this document, I felt the completed scripts was
lengthy, redundant and not easy to read. So I didn't add complete
examples in the previous commit.
However, in the recent discussion with @avogelsgesang, I found people
may not know how to use debugging scripts to improve their debugging
efficiency. So now, I feel like it is helpful to put the examples even
if they are a little bit long.
Test Plan: make docs-clang-html
Reviewed By: avogelsgesang
Differential Revision: https://reviews.llvm.org/D132451
Previously in D99179, I tried to construct debug information for
coroutine frames in the middle end to enhance the debugability for
coroutines. But I forget to add ReleaseNotes to hint people and
documents to help people to use. My bad. @probinson revealed this in
https://github.com/llvm/llvm-project/issues/55916.
So I try to add the use document now.
Reviewed By: erichkeane
Differential Revision: https://reviews.llvm.org/D127626
