Issue 221105.1: Add a mechanism for specifying subprogram return value locations

Author:	Kyle Huey
Champion:	Andrew Cagney
Date submitted:	2022-11-05
Date revised:	2024-12-09
Date closed:
Type:	Enhancement
Status:	Open
DWARF version:	6

Section 3.3.2, pg 78

Background

A debug feature is to print the value returned by a subprogram.

In GDB (and I assume LLDB) this is implemented as follows:

• create an identifier of the caller of the subprogram instance

  for instance, { function's entry point, the CFI's CFA }

  When there's recursion this is to differentiate between otherwise identical instances.

• breakpoint the instruction that the subprogram will return to, i.e., in the calling subprogram

  for instance, CFI's return address

• breakpoint any code that can longjump around caller

  so that the return breakpoint can be deleted

• resume the program

• when the breakpoint hits:

  • if the frame is older then the caller - longjump - abort
  • if the frame is newer than the caller - recursion - continue
  • if the frame matches, ya!

• extract and display the return value using the callers context

While DWARF makes available the type of the return value (DW_AT_type attached to DW_TAG_subprogram, as detailed in Section 3.3.2), it does not provide a mechanism for obtaining the value being returned by a subprogram immediately after the return instuction. Instead consumers use hardwired, and assumed, ABI knowlege to obtain the value.

This has a number of limitations:

• the consumer's ABI knowledge is hard-wired

  It isn't possible for a producer to generate code following different conventions without also modifying the consumer.

  For instance: a Language (here Rust) uses a calling convention not covered by the ABI; the compiler optimises a subprogram causing the calling convention to change.

• the returned value's location may be unknown

  For instance, when the the return value's memory location is passed in as a hidden first parameter (aka struct return) that location is unknown at the time of return

• when a subprogram is inlined

  Similar to the non-inline case, DWARF makes available tye subprogram's return type (DW_AT_type in DW_TAG_inlined_subroutine via DW_AT_abstract_origin) but not the location of the returned value.

  However, it is very unlikely that the inlined code follows any calling convention.

(While attaching DW_AT_calling_convention DW_CC_nocall to the subprogram could be used to signal that the ABI is not being followed, this isn't about the consumer simulating a call).

Please note that this is not proposing a mechanism for locating a subprogram's return value while inside the function such as at the return instruction.

Proposal Part 1: add DW_AT_result_location to DW_AT_subprogram

Add the attribute DW_AT_result_location to DW_AT_subprogram. This attribute describes the location of the value returned by the program after the subprogram has returned.

Because the subprogram has exited it uses the CFI of the calling subprogram.

Some notes:

• Why the new attribute DW_AT_result_location (instead of using DW_AT_location)?

  A location description:

  Single location descriptions, [...]. They are sufficient for describing the location of any object as long as its lifetime is either static or the same as the lexical block that owns it, [...]

  Here the description, while owned by the subprogram, is interpreted using the lexical block of the caller.

Change Details

Called Subprograms

In 3.3.2 Subroutine and Entry Point Return Types, change the section heading to:

3.3.2 Subroutine and Entry Point Return Type and Value

At the end of the section, which currently reads:

If the subroutine or entry point is a function that returns a value, then its debugging information entry has a DW_AT_type attribute to denote the type returned by that function.

Add the paragraph and non-normative text:

A subroutine or entry point that is a function that returns a value and has a DW_AT_type attribute may also have a DW_AT_result_location attribute. This attribute specifies the location of the return value after the called function has returned and the calling subprogram is about to be resumed.

Since the called subprogram has returned, the location description is relative to the calling subprogram. For instance, for a sliding window architecture such as SPARC, the location description refers to the output registers of the caller, and not the input registers of the callee.

When the both the attribute DW_AT_result_location and DW_CC_nocall are both omitted, the subprogram is assumed to comply with ABI calling conventions.

Call Site Entries and Parameters

In 3.4 Call Site Entries and Parameters, change the section title to:

3.4 Call Site Entries, Parameters, and Return Value

Change the opening non-normative paragraph from:

A call site entry describes a call from one subprogram to another in the source program. It provides information about the actual parameters of the call so that they may be more easily accessed by a debugger. When used together with call frame information (see Section 6.4 on page 178), call site entries can be useful for computing the value of an actual parameter passed by a caller, even when the location description for the callee’s corresponding formal parameter does not provide a current location for the formal parameter.

to:

A call site entry describes a call from one subprogram to another in the source program. It provides information about both the actual parameters of the call, and the location of the return value after the subprogram returns, so that they may be more easily accessed by a debugger. Independent of the location description of the callee’s corresponding formal parameters and DW_AT_result_location attribute, the Call Site entry can be used together with call frame information (see Section 6.4 on page 178) to compute the value of an actual parameter passed by a caller and the return value after the callee returns.

In 3.4.2 Call Site Parameters, change the section title to:

3.4.2 Call Site Parameters and Return Value

At the end of the section add the paragraph and non-normative text:

A call site entry that has a DW_AT_type attribute for the type of the called function, may have a DW_AT_result_location attribute specifying the location of the return value after the called function has returned and the calling subprogram is about to be resumed.

Since the function described by the Call Site Entry's DW_AT_type attribute can be abstract, the return type and location may be different between the Call Site and the subprogram.

Inlined Subprograms

In 3.3.8.1 Abstract Instances

Change the non-normative text:

For example, the DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges, DW_AT_entry_pc, DW_AT_location, DW_AT_return_addr and DW_AT_start_scope attributes typically should be omitted; however, this list is not exhaustive.

to:

For example, the DW_AT_low_pc, DW_AT_high_pc, DW_AT_ranges, DW_AT_entry_pc, DW_AT_location, DW_AT_return_addr, DW_AT_result_location, and DW_AT_start_scope attributes typically should be omitted; however, this list is not exhaustive.

(i.e, add DW_AT_result_location)

In 3.3.8.2 Concrete Instances, following the paragraph:

An inlined subroutine entry may have a DW_AT_const_expr attribute, [...], represented as it would be on the target architecture. ....

Add the paragraph and non-normative text:

An inlined subroutine entry that is a function that returns a value and and has DW_AT_type defined in the Abstract Instance may have a DW_AT_result_location attribute. This attribute describes the location of the return value immediately after the concrete instance has completed execution of the contiguous or non-contiguous machine instructions generated for the inlined subroutine.

Since the concrete instance may consist of non-contiguous instructions, DW_AT_result_location may be defined using a Location List. Within that list, each bounded entry identifies an instruction immediately after the concrete instance has completed execution. That list of locations may not be exhaustive.

Appendix A. Attributes by Tag (Informative)

Add DW_AT_result_location to:

• DW_TAG_subprogram
• DW_TAG_call_site
• DW_TAG_inlined_subroutine

Appendix D

[Example TBD]

---

2022-11-05: Original proposal.

2023-11-05: Rewrote.

2024-01-08: Revised with more non-normative text.

2024-02-05: Added section on call sites.

2024-03-04: Revised to add ABI fallback and address questions about call sites.

2024-04-29: Needs revision to use DW_AT_result_location.

2024-12-09: Revised.