[PATCH] libdw: Update dwarf_cu_dwp_section_info documentation

[Mark Wielaard]

Update the documentation of dwarf_cu_dwp_section_info to make clear
that the function only returns an error if the DWARF package file data
couldn't be read or an unknown section constant is provided.  Missing
DWP information for a given CU isn't an error and will set both OFFSET
and SIZE to zero.  It also makes sure the documentation is < 76 chars
wide.

* libdw/libdw.h (dwarf_cu_dwp_section_info): Update docs.

Signed-off-by: Mark Wielaard 
---
 libdw/libdw.h | 42 +++---
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/libdw/libdw.h b/libdw/libdw.h
index 545ad043..d53dc787 100644
--- a/libdw/libdw.h
+++ b/libdw/libdw.h
@@ -1081,25 +1081,29 @@ extern int dwarf_frame_register (Dwarf_Frame *frame, 
int regno,
   __nonnull_attribute__ (3, 4, 5);
 
 
-/* Return offset and/or size of CU's contribution to SECTION in a DWARF package
-   file.
-
-   If CU is not from a DWARF package file, the file does not have SECTION, or 
CU
-   does not contribute to SECTION, then *SIZEP is set to 0.
-
-   SECTION is a DW_SECT section identifier.  Note that the original GNU DWARF
-   package file extension for DWARF 4 used slightly different section
-   identifiers.  This function uses the standardized section identifiers and
-   maps the GNU DWARF 4 identifiers to their standard DWARF 5 analogues:
-   DW_SECT_LOCLISTS (5) refers to .debug_locs.dwo for DWARF 4.
-   DW_SECT_MACRO (7) refers to .debug_macinfo.dwo for DWARF 4 or
-   .debug_macro.dwo for the GNU .debug_macro extension for DWARF 4 (section
-   identifier 8 is DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the
-   GNU extension.)
-   .debug_types.dwo does not have a DWARF 5 equivalent, so this function 
accepts
-   the original DW_SECT_TYPES (2).
-
-   Returns 0 for success or -1 for errors.  OFFSETP and SIZEP may be NULL.  */
+/* Return offset and/or size of CU's contribution to SECTION in a
+   DWARF package file.
+
+   If CU is not from a DWARF package file, the file does not have
+   SECTION, or CU does not contribute to SECTION, then *OFFSETP and
+   *SIZEP are set to 0 (this is not an error and the function will
+   return 0 in that case).
+
+   SECTION is a DW_SECT section identifier.  Note that the original
+   GNU DWARF package file extension for DWARF 4 used slightly
+   different section identifiers.  This function uses the standardized
+   section identifiers and maps the GNU DWARF 4 identifiers to their
+   standard DWARF 5 analogues: DW_SECT_LOCLISTS (5) refers to
+   .debug_locs.dwo for DWARF 4.  DW_SECT_MACRO (7) refers to
+   .debug_macinfo.dwo for DWARF 4 or .debug_macro.dwo for the GNU
+   .debug_macro extension for DWARF 4 (section identifier 8 is
+   DW_SECT_RNGLISTS in DWARF 5, NOT DW_SECT_MACRO like in the GNU
+   extension.)  .debug_types.dwo does not have a DWARF 5 equivalent,
+   so this function accepts the original DW_SECT_TYPES (2).
+
+   Returns 0 for success or -1 for errors reading the DWARF package
+   file data or if an unknown SECTION constant is given.  OFFSETP and
+   SIZEP may be NULL.  */
 extern int dwarf_cu_dwp_section_info (Dwarf_CU *cu, unsigned int section,
  Dwarf_Off *offsetp, Dwarf_Off *sizep);
 
-- 
2.43.2

Re: [PATCH v2 3/4] libdw: Apply DWARF package file section offsets where appropriate

[Mark Wielaard]

Hi Omar,

On Wed, 2023-12-06 at 01:22 -0800, Omar Sandoval wrote:
> The final piece of DWARF package file support is that offsets have to be
> interpreted relative to the section offset from the package index.
> .debug_abbrev.dwo is already covered, so sprinkle around calls to
> dwarf_cu_dwp_section_info for the remaining sections: .debug_line.dwo,
> .debug_loclists.dwo/.debug_loc.dwo, .debug_str_offsets.dwo,
> .debug_macro.dwo/.debug_macinfo.dwo, and .debug_rnglists.dwo.  With all
> of that in place, we can finally test various libdw functions on dwp
> files.

So the offsets for DW_SECT_INFO, DW_SECT_TYPES and DW_SECT_ABBREV were
already taken into account when setting up a cu from a dwp.

With this patch __libdw_cu_str_off_base/str_offsets_base_off handles
DW_SECT_STR_OFFSETS which is used in dwarf_formstring and
dwarf_getmacros.

__libdw_cu_ranges_base handles DW_SECT_RNGLISTS, which is used by
dwarf_ranges. And __libdw_formptr has a special case for
DW_FORM_sec_offset for IDX_debug_ranges && version < 5 && unit_type ==
DW_UT_split_compile to also uses __libdw_cu_ranges_base.

__libdw_cu_locs_base handles DW_SECT_LOCLISTS which is used in
dwarf_getlocation through initial_offset. I do wonder why the special
case in __libdw_formptr isn't needed here too.

dwarf_getmacros handles DW_SECT_MACRO through get_offset_from. And when
the macros need to refer to the line table, it also handles
DW_SECT_LINE.

Don't we also need to handle DW_SECT_LINE in dwarf_getsrclines and
dwarf_next_lines when looking for DW_AT_stmt_list?

>   * libdw/dwarf_getmacros.c (get_macinfo_table): Call
>   dwarf_cu_dwp_section_info and add offset to line_offset.
>   (get_offset_from): Call dwarf_cu_dwp_section_info and add offset
>   to *retp.
>   * libdw/libdwP.h (str_offsets_base_off): Call
>   dwarf_cu_dwp_section_info and add offset.
>   (__libdw_cu_ranges_base): Ditto.
>   (__libdw_cu_locs_base): Ditto.
>   * libdw/dwarf_getlocation.c (initial_offset): Call
>   dwarf_cu_dwp_section_info and add offset to start_offset.
>   * tests/run-varlocs.sh: Check testfile-dwp-5 and testfile-dwp-4.
>   * tests/run-all-dwarf-ranges.sh: Check testfile-dwp-5 and
>   testfile-dwp-4.
>   * tests/run-dwarf-getmacros.sh: Check testfile-dwp-5 and
>   testfile-dwp-4-strict.
>   * tests/run-get-units-split.sh: Check testfile-dwp-5,
>   testfile-dwp-4, and testfile-dwp-4-strict.

The code and tests look good. run-varlocs.sh seems good, which seems to
confirm DW_SECT_LOCLISTS is handled correctly (but why doesn't it need
a hack similar to ranges in __libdw_formptr?).

We might want to add a test for run-next-lines.sh and run-next-
files.sh?

Thanks,

Mark