From: Simon Marchi <simon.marchi@polymtl.ca>
Date: Fri, 21 Nov 2025 20:14:05 +0000 (-0500)
Subject: gdb/dwarf: clarify meaning dwarf2_per_cu::{m_section,m_sect_off,m_length} in presence... 
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b053b7b5b409875454f9655bf82b8a6f61a7edfc;p=thirdparty%2Fbinutils-gdb.git

gdb/dwarf: clarify meaning dwarf2_per_cu::{m_section,m_sect_off,m_length} in presence of DWO file

The comments above these fields are almost accurate.  If a unit in a DWO
file has a corresponding skeleton in the main file, these fields
describe the skeleton in the main file.  However, it's missing the
detail that if the unit in the DWO file does not have a corresponding
skeleton in the main file, then the fields describe the unit in the DWO
file.  Update the comments to reflect that.

Change-Id: I0681bc0d884f7e373b227416cbdef307d462ae71
Approved-By: Tom Tromey <tom@tromey.com>
---

diff --git a/gdb/dwarf2/read.h b/gdb/dwarf2/read.h
index bcbd18296ec..412b5a2d9b1 100644
--- a/gdb/dwarf2/read.h
+++ b/gdb/dwarf2/read.h
@@ -136,13 +136,26 @@ struct dwarf2_per_cu
   }
 
 private:
-  /* The start offset and length of this compilation unit.
-     NOTE: Unlike comp_unit_head.length, this length includes
-     initial_length_size.
-     If the DIE refers to a DWO file, this is always of the original die,
-     not the DWO file.  */
+  /* The start offset of this unit.
+
+     If the unit is located in a DWO file, and has a corresponding skeleton
+     unit in the main file, this is the offset of the skeleton unit in its
+     containing section in the main file.
+
+     If the unit is located in a DWO file, but has no corresponding skeleton
+     unit in the main file, this is the offset of the unit in its containing
+     section in the DWO file.  */
   sect_offset m_sect_off;
 
+  /* The length of this unit.
+
+     If the unit is located in a DWO file, and has a corresponding skeleton unit
+     in the main file, this is the length of the skeleton unit in the main file.
+
+     If the unit is located in a DWO file, but has no corresponding skeleton
+     unit in the main file, this is the length of the unit in the DWO file.
+
+     Unlike unit_head::m_length, this length includes initial_length_size.  */
   unsigned int m_length = 0;
 
 private:
@@ -225,9 +238,15 @@ public:
   unsigned index = 0;
 
 private:
-  /* The section this CU/TU lives in.
-     If the DIE refers to a DWO file, this is always the original die,
-     not the DWO file.  */
+  /* The section this unit lives in.
+
+     If the unit is located in a DWO file, and has a corresponding skeleton unit
+     in the main file, this is the section of the skeleton unit in the main
+     file.
+
+     If the unit is located in a DWO file, but has no corresponding skeleton
+     unit in the main file, this is the section of the unit in the DWO
+     file.  */
   dwarf2_section_info *m_section;
 
   /* Backlink to the owner of this.  */