xref: /illumos-gate/usr/src/lib/libdwarf/common/dwarf_opaque.h (revision 4d9fdb46b215739778ebc12079842c9905586999)
1 /*
2   Copyright (C) 2000-2005 Silicon Graphics, Inc.  All Rights Reserved.
3   Portions Copyright (C) 2007-2019 David Anderson. All Rights Reserved.
4   Portions Copyright (C) 2008-2010 Arxan Technologies, Inc. All Rights Reserved.
5 
6   This program is free software; you can redistribute it
7   and/or modify it under the terms of version 2.1 of the
8   GNU Lesser General Public License as published by the Free
9   Software Foundation.
10 
11   This program is distributed in the hope that it would be
12   useful, but WITHOUT ANY WARRANTY; without even the implied
13   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
14   PURPOSE.
15 
16   Further, this software is distributed without any warranty
17   that it is free of the rightful claim of any third person
18   regarding infringement or the like.  Any license provided
19   herein, whether implied or otherwise, applies only to this
20   software file.  Patent licenses, if any, provided herein
21   do not apply to combinations of this program with other
22   software, or any other product whatsoever.
23 
24   You should have received a copy of the GNU Lesser General
25   Public License along with this program; if not, write the
26   Free Software Foundation, Inc., 51 Franklin Street - Fifth
27   Floor, Boston MA 02110-1301, USA.
28 
29 */
30 /*  Following the nomenclature of the DWARF standard
31     Section Version Numbers (DWARF 5):
32     * means not applicable.
33     - means not defined in that version.
34     The version numbers for .debug_info is the same as .debug_info.dwo
35     (etc for the other dwo sections).
36     The versions applicable by section are:
37     .                  DWARF2 DWARF3 DWARF4 DWARF5
38     .debug_abbrev           *      *      *      *
39     .debug_addr             -      -      -      5
40     .debug_aranges          2      2      2      2
41     .debug_frame            1      3      4      4
42     .debug_info             2      3      4      5
43     .debug_line             2      3      4      5
44     .debug_line_str         -      -      -      5
45     .debug_loc              *      *      *      -
46     .debug_loclists         -      -      -      5
47     .debug_macinfo          *      *      *      -
48     .debug_macro            -      -      -      5
49     .debug_names            -      -      -      5
50     .debug_pubnames         2      2      2      -
51     .debug_pubtypes         -      2      2      -
52     .debug_ranges           -      *      *      -
53     .debug_rnglists         -      -      -      5
54     .debug_str              *      *      *      *
55     .debug_str_offsets      -      -      -      5
56     .debug_sup              -      -      -      5
57     .debug_types            -      -      4      -
58 
59     .debug_abbrev.dwo       -      -      -      *
60     .debug_info.dwo         -      -      -      5
61     .debug_line.dwo         -      -      -      5
62     .debug_loc.dwo          -      -      -      -
63     .debug_loclists.dwo     -      -      -      5
64     .debug_macro.dwo        -      -      -      5
65     .debug_rnglists.dwo     -      -      -      5
66     .debug_str.dwo          -      -      -      *
67     .debug_str_offsets.dwo  -      -      -      5
68 
69     .debug_cu_index         -      -      -      5
70     .debug_tu_index         -      -      -      5
71 
72 */
73 
74 struct Dwarf_Rnglists_Context_s;
75 typedef struct Dwarf_Rnglists_Context_s *Dwarf_Rnglists_Context;
76 struct Dwarf_Loclists_Context_s;
77 typedef struct Dwarf_Loclists_Context_s *Dwarf_Loclists_Context;
78 
79 struct Dwarf_Die_s {
80     Dwarf_Byte_Ptr di_debug_ptr;
81     Dwarf_Abbrev_List di_abbrev_list;
82     Dwarf_CU_Context di_cu_context;
83     int  di_abbrev_code;
84 
85     /* TRUE if part of debug_info. FALSE if part of .debug_types. */
86     Dwarf_Bool di_is_info;
87 };
88 
89 struct Dwarf_Attribute_s {
90     Dwarf_Half ar_attribute;             /* Attribute Value. */
91     Dwarf_Half ar_attribute_form;        /* Attribute Form. */
92     Dwarf_Half ar_attribute_form_direct;
93         /*  Identical to ar_attribute_form except that if
94             the original form uleb was DW_FORM_indirect,
95             ar_attribute_form_direct contains DW_FORM_indirect
96             but ar_attribute_form contains the true form. */
97     Dwarf_CU_Context ar_cu_context;
98         /*  The following points to either debug_info or debug_types
99             depending on if context is cc_is_info  or not. */
100     Dwarf_Small *ar_debug_ptr;
101         /*  If DW_FORM_implicit const, the value is here, not
102             in the DIE. */
103     Dwarf_Signed ar_implicit_const;
104     Dwarf_Debug  ar_dbg; /* dbg owning the attr */
105 
106     Dwarf_Die ar_die;/* Access to the DIE owning the attribute */
107     Dwarf_Attribute ar_next;
108 };
109 
110 
111 /*
112     This structure provides the context for a compilation unit.
113     Thus, it contains the Dwarf_Debug, cc_dbg, that this cu
114     belongs to.  It contains the information in the compilation
115     unit header, cc_length, cc_version_stamp, cc_abbrev_offset,
116     and cc_address_size, in the .debug_info section for that cu.
117     In addition, it contains the count, cc_count_cu, of the cu
118     number of that cu in the list of cu's in the .debug_info.
119     The count starts at 1, ie cc_count_cu is 1 for the first cu,
120     2 for the second and so on.  This struct also contains a
121     pointer, cc_abbrev_table, to a list of pairs of abbrev code
122     and a pointer to the start of that abbrev
123     in the .debug_abbrev section.
124 
125     Each die will also contain a pointer to such a struct to
126     record the context for that die.
127 
128     Notice that a pointer to the CU DIE itself is
129     Dwarf_Off off2 = cu_context->cc_debug_info_offset;
130     cu_die_info_ptr = dbg->de_debug_info.dss_data +
131         off2 + _dwarf_length_of_cu_header(dbg, off2);
132     Or similar for de_debug_types.
133 
134     **Updated by dwarf_next_cu_header in dwarf_die_deliv.c
135 */
136 struct Dwarf_CU_Context_s {
137     Dwarf_Debug cc_dbg;
138     /*  The sum of cc_length, cc_length_size, and cc_extension_size
139         is the total length of the CU including its header.
140 
141         cc_length is the length of the compilation unit excluding
142         cc_length_size and cc_extension_size.  */
143     Dwarf_Unsigned cc_length;
144 
145     /*  cc_length_size is the size in bytes of an offset.
146         Should probably be renamed cc_offset_size.
147         4 for 32bit dwarf, 8 for 64bit dwarf (whether MIPS/IRIX
148         64bit dwarf or standard 64bit dwarf using the extension
149         mechanism). */
150     Dwarf_Small cc_length_size;
151 
152     /*  cc_extension_size is zero unless this is standard
153         DWARF3 and later 64bit dwarf using the extension mechanism.
154         64bit DWARF3 and later: cc_extension_size is 4.
155         64bit DWARF2 MIPS/IRIX: cc_extension_size is zero.
156         32bit DWARF:            cc_extension_size is zero.  */
157     Dwarf_Small cc_extension_size;
158 
159     /*  cc_version_stamp is the DWARF version number applicable
160         to the  DWARF in this compilation unit. 2,3,4,... */
161     Dwarf_Half cc_version_stamp;
162     /*  cc_abbrev_offset is the section-global offset
163         of the .debug_abbrev section this CU uses.
164         Data from CU header. Includes DWP adjustment made
165         as soon as we create a cu_context. */
166     Dwarf_Unsigned cc_abbrev_offset;
167 
168     /*  cc_address_size is the size of an address in this
169         compilation unit. */
170     Dwarf_Small cc_address_size;
171     Dwarf_Small cc_segment_selector_size;
172 
173     /*  cc_debug_offset is the global offset in the section
174         of the CU header of this CU.
175         That is, it is a section global offset.
176         May be debug_info or debug_types
177         but those are distinct.
178         Even in DWP this is set to true global offset
179         right away when cu_context created.
180         See cc_is_info flag. */
181     Dwarf_Unsigned cc_debug_offset;
182 
183     /* === START DEBUG FISSION (Split Dwarf) data
184         cc_signature is in the TU header
185         of a type unit of a TU DIE (or for DW5 in the
186         skeleton or split_compile header is a dwo_id).
187         Ignore this field if cc_signature_present is zero.
188         (TU CUs signature is not the same namespace
189         as DW_AT_dwo_id signatures. The two must be
190         kept separate (for DWARF5))
191 
192         If cc_unit_type == DW_UT_compile or DW_UT_partial
193             the signature is a CU signature (dwo_id).
194         Some early DW5 drafts encouraged DWARF4 output
195             of some compilers to include dwo_id, but
196             in a messier way(lacking DW_UT_*).
197         If cc_unit_type == DW_UT_type ( DW_UT_split_type
198             was never part of DW5, never standard).
199             the signature is a type signature. */
200 
201     Dwarf_Half  cc_cu_die_tag;
202     Dwarf_Sig8  cc_signature;
203 
204     /*  cc_type_signature_offset contains the
205         section-local DIE offset of the type
206         the signature applies to if the cc_unit_type
207         is DW_UT_type or DW_UT_split_type. */
208     Dwarf_Unsigned cc_signature_offset;
209 
210     /*  For each CU and each TU
211         in a dwp package file there is
212         is a hash and
213         a set of offsets indexed by DW_SECT_* id.
214         Only one such set per CU or TU.
215         The data on all that is in cc_dwp_offsets
216 
217         If it is a TU the signature in cc_dwp_offsets
218         must match the signature in cc_signature.
219         */
220     struct Dwarf_Debug_Fission_Per_CU_s  cc_dwp_offsets;
221 
222     Dwarf_Bool cc_signature_present; /* Meaning type signature
223         in TU header or, for CU header, signature in CU DIE. */
224     Dwarf_Bool cc_low_pc_present;
225     Dwarf_Bool cc_addr_base_present;   /* Not TRUE in .dwo */
226     /*  DW_AT_GNU_ranges_base was a GNU extension that appeared
227         but was unused. See dwarf_die_deliv.c for details. */
228     Dwarf_Bool cc_ranges_base_present; /* unused */
229     Dwarf_Bool cc_rnglists_base_present; /* DW5 */
230     Dwarf_Bool cc_str_offsets_base_present;
231     Dwarf_Bool cc_loclists_base_present;
232     Dwarf_Bool cc_cu_die_has_children;
233     Dwarf_Bool cc_dwo_name_present;
234 
235     /*  Non zero if this context is a dwo section. Either
236         dwo or dwp file. */
237     Dwarf_Bool cc_is_dwo;
238 
239     /*  cc_cu_die_offset_present is non-zero if
240         cc_cu_die_global_sec_offset is meaningful.  */
241     Dwarf_Bool cc_cu_die_offset_present;
242 
243     /* if present, is base address of CU */
244     Dwarf_Unsigned cc_low_pc;
245     /*  from DW_AT_addr_base in CU DIE, offset to .debug_addr table */
246     Dwarf_Unsigned cc_addr_base;     /* Zero in .dwo */
247     /*  DW_AT_GNU_ranges_base was a GNU extension that appeared
248         but was unused. See dwarf_die_deliv.c for details. */
249     Dwarf_Unsigned cc_ranges_base;   /* unused */
250     /*  from DW_AT_rnglists_base in CU DIE */
251     Dwarf_Unsigned cc_rnglists_base;    /*DW5 */
252     /*  from DW_AT_str_offsets_base in CU DIE */
253     Dwarf_Unsigned cc_str_offsets_base;
254     /*  From DW_AT_loclists_base */
255     Dwarf_Unsigned cc_loclists_base;
256 
257     char *     cc_dwo_name;
258     /* === END DEBUG FISSION (Split Dwarf) data */
259 
260     /*  Global section offset to the bytes of the CU die for this CU.
261         Set when the CU die is accessed by dwarf_siblingof_b(). */
262     Dwarf_Unsigned cc_cu_die_global_sec_offset;
263 
264 
265     Dwarf_Byte_Ptr cc_last_abbrev_ptr;
266     Dwarf_Byte_Ptr cc_last_abbrev_endptr;
267     Dwarf_Hash_Table cc_abbrev_hash_table;
268     Dwarf_CU_Context cc_next;
269 
270     /*unsigned char cc_offset_length; */
271     Dwarf_Bool cc_is_info; /* TRUE means context is
272         in debug_info, FALSE means is in debug_types.
273         FALSE only possible for DWARF4 .debug_types
274         section CUs.
275         For DWARF5 all DIEs are in .debug_info[.dwo] */
276 
277     Dwarf_Half cc_unit_type;
278         /*  DWARF5: set from header
279             For DWARF 2,3,4 this is filled in initially
280         from the CU header and refined by inspecting
281         the CU DIE to detect the correct setting. */
282 
283 };
284 
285 /*  Consolidates section-specific data in one place.
286     Section is an Elf specific term, intended as a general
287     term (for non-Elf objects some code must synthesize the
288     values somehow).  */
289 struct Dwarf_Section_s {
290     Dwarf_Small *  dss_data;
291     Dwarf_Unsigned dss_size;
292     /*  Some Elf sections have a non-zero dss_entrysize which
293         is the size in bytes of a table entry in the section.
294         Relocations and symbols are both in tables, so have a
295         non-zero entrysize.  Object formats which do not care
296         about this should leave this field zero. */
297     Dwarf_Unsigned dss_entrysize;
298     /*  dss_index is the section index as things are numbered in
299         an object file being read.   An Elf section number. */
300     Dwarf_Unsigned     dss_index;
301     /*  dss_addr is the 'section address' which is only
302         non-zero for a GNU eh section.
303         Purpose: to handle DW_EH_PE_pcrel encoding. Leaving
304         it zero is fine for non-elf.  */
305     Dwarf_Addr     dss_addr;
306     Dwarf_Small    dss_data_was_malloc;
307     /*  is_in_use set during initial object reading to
308         detect duplicates. Ignored after setup done. */
309     Dwarf_Small    dss_is_in_use;
310 
311     /*  When loading COMDAT they refer (sometimes) to
312         base sections, so we need to have the BASE
313         group sections filled in when the corresponding is
314         not in the COMDAT group list.  .debug_abbrev is
315         an example. */
316     Dwarf_Unsigned     dss_group_number;
317 
318     /* These for reporting compression */
319     Dwarf_Unsigned dss_uncompressed_length;
320     Dwarf_Unsigned dss_compressed_length;
321 
322     /*  If this is zdebug, to start  data/size are the
323         raw section bytes.
324         Initially for all sections dss_data_was_malloc set FALSE
325             and dss_requires_decompress set FALSE.
326         For zdebug set dss_zdebug_requires_decompress set TRUE
327             In that case it is likely ZLIB compressed but
328             we do not know that just scanning section headers.
329         If not .zdebug but it is SHF_COMPRESSED
330             then decompress is required.
331 
332         On translation (ie zlib use and malloc)
333         Set dss_data dss_size to point to malloc space and
334             malloc size.
335         Set dss_did_decompress FALSE
336         Set dss_was_malloc  TRUE */
337     Dwarf_Small    dss_zdebug_requires_decompress;
338     Dwarf_Small    dss_did_decompress;
339     Dwarf_Small dss_shf_compressed;  /* section flag SHF_COMPRESS */
340     Dwarf_Small dss_ZLIB_compressed; /* Section compression starts with ZLIB chars*/
341 
342     /*  For non-elf, leaving the following fields zero
343         will mean they are ignored. */
344     /*  dss_link should be zero unless a section has a link
345         to another (sh_link).  Used to access relocation data for
346         a section (and for symtab section, access its strtab). */
347     Dwarf_Unsigned     dss_link;
348     /*  The following is used when reading .rela sections
349         (such sections appear in some .o files). */
350     Dwarf_Half     dss_reloc_index; /* Zero means ignore the reloc fields. */
351     Dwarf_Small *  dss_reloc_data;
352     Dwarf_Unsigned dss_reloc_size;
353     Dwarf_Unsigned dss_reloc_entrysize;
354     Dwarf_Addr     dss_reloc_addr;
355     /*  dss_reloc_symtab is the sh_link of a .rela to its .symtab, leave
356         it 0 if non-meaningful. */
357     Dwarf_Addr     dss_reloc_symtab;
358     /*  dss_reloc_link should be zero unless a reloc section has a link
359         to another (sh_link).  Used to access the symtab for relocations
360         a section. */
361     Dwarf_Unsigned     dss_reloc_link;
362     /*  Pointer to the elf symtab, used for elf .rela. Leave it 0
363         if not relevant. */
364     struct Dwarf_Section_s *dss_symtab;
365     /*  dss_name, dss_standard_name must never be freed,
366         they are static strings in libdwarf. */
367     const char * dss_name;
368     const char * dss_standard_name;
369 
370     /* Object section number in object file. */
371     unsigned dss_number;
372 
373     /*  These are elf flags and non-elf object should
374         just leave these fields zero. Which is essentially
375         automatic as they are not in
376         Dwarf_Obj_Access_Section_s.  */
377     Dwarf_Unsigned  dss_flags;
378     Dwarf_Unsigned  dss_addralign;
379 
380     /*  Set when loading .group section as those are special and
381         neither compressed nor have relocations so never malloc
382         space for libdwarf.  */
383     Dwarf_Small     dss_ignore_reloc_group_sec;
384     char dss_is_rela;
385 };
386 
387 /*  Overview: if next_to_use== first, no error slots are used.
388     If next_to_use+1 (mod maxcount) == first the slots are all used
389 */
390 struct Dwarf_Harmless_s {
391   unsigned dh_maxcount;
392   unsigned dh_next_to_use;
393   unsigned dh_first;
394   unsigned dh_errs_count;
395   char **  dh_errors;
396 };
397 
398 /* Data needed seperately for debug_info and debug_types
399    as we may be reading both interspersed. */
400 
401 struct Dwarf_Debug_InfoTypes_s {
402     /*  Context for the compilation_unit just read by a call to
403         dwarf_next_cu_header. **Updated by dwarf_next_cu_header in
404         dwarf_die_deliv.c */
405     Dwarf_CU_Context de_cu_context;
406     /*  Points to linked list of CU Contexts for the
407         CU's already read.  These are only CU's read
408         by dwarf_next_cu_header(). */
409     Dwarf_CU_Context de_cu_context_list;
410     /*  Points to the last CU Context added to the list by
411         dwarf_next_cu_header(). */
412     Dwarf_CU_Context de_cu_context_list_end;
413 
414     /*  Offset of last byte of last CU read.
415         Actually one-past that last byte.  So
416         use care and compare as offset >= de_last_offset
417         to know if offset is too big. */
418     Dwarf_Unsigned de_last_offset;
419     /*  de_last_di_info_ptr and de_last_die are used with
420         dwarf_siblingof, dwarf_child, and dwarf_validate_die_sibling.
421         dwarf_validate_die_sibling will not give meaningful results
422         if called inappropriately. */
423     Dwarf_Byte_Ptr  de_last_di_ptr;
424     Dwarf_Die  de_last_die;
425 };
426 typedef struct Dwarf_Debug_InfoTypes_s *Dwarf_Debug_InfoTypes;
427 
428 /*  As the tasks performed on a debug related section is the same,
429     in order to make the process of adding a new section
430     (very unlikely) a little bit easy and to reduce the
431     possibility of errors, a simple table
432     build dynamically, will contain the relevant information.
433 */
434 
435 struct Dwarf_dbg_sect_s {
436     /*  Debug section name must not be freed, is quoted string.
437         This is the name from the object file itself. */
438     const char *ds_name;
439     /* The section number in object section numbering. */
440     unsigned ds_number;
441     /*   Debug section information, points to de_debug_*member
442         (or the like) of the dbg struct.  */
443     struct Dwarf_Section_s *ds_secdata;
444 
445     unsigned ds_groupnumber;
446     int ds_duperr;                     /* Error code for duplicated section */
447     int ds_emptyerr;                   /* Error code for empty section */
448     int ds_have_dwarf;                 /* Section contains DWARF */
449     int ds_have_zdebug;                /* Section compressed: .zdebug name */
450 };
451 
452 /*  As the number of debug sections does not change very often, in the case a
453     new section is added in 'enter_section_in_array()'
454     the 'MAX_DEBUG_SECTIONS' must
455     be updated accordingly.
456     This does not yet allow for section-groups in object files,
457     for which many .debug_info (and other) sections may exist.
458 */
459 #define DWARF_MAX_DEBUG_SECTIONS 50
460 #define DWARFSTRING_ALLOC_SIZE   200
461 
462 
463 /*  All the Dwarf_Debug tied-file info in one place.  */
464 struct Dwarf_Tied_Data_s {
465     /*  Used to access executable from .dwo or .dwp object.
466         Pointer to the tied_to Dwarf_Debug*/
467     Dwarf_Debug td_tied_object;
468 
469     /*  TRUE if this tied object is tied to.
470         It's extra work to look for a DW_AT_dwo_id.
471         Set when tied dbg (on the base) was created.
472         This helps us do it only when it may be productive. */
473     Dwarf_Bool td_is_tied_object;
474 
475     /*  Used for Type Unit signatures.
476         Type Units are in .debug_types in DW4
477         but in .debug_info in DW5.
478         Some .debug_info point to them symbolically
479         via DW_AT_signature attributes.
480         If non-zero is a dwarf_tsearch 'tree'.
481         Only non-zero if td_is_tied_object is set and
482         we had a reason to build the search tree..
483         Type Units have a Dwarf_Sig8 signature
484         in the header, and such is recorded here.
485 
486         Type Unit signatures can conflict with
487         signatures in split-dwarf (dwo/dwp) sections.
488 
489         The Key for each record is a Dwarf_Sig8 (8 bytes).
490         The data for each is a pointer to a Dwarf_CU_context
491         record in this dbg (cu_context in
492         one of tied dbg's de_cu_context_list). */
493     void *td_tied_search;
494 
495 };
496 
497 /*  dg_groupnum 0 does not exist.
498     dg_groupnum 1 is base
499     dg_groupnum 2 is dwo
500     dg_groupnum 3 and higher are COMDAT groups (if any).
501   */
502 struct Dwarf_Group_Data_s {
503     /* For traditional DWARF the value is one, just one group. */
504     unsigned gd_number_of_groups;
505 
506     /* Raw elf (elf-like) section count. */
507     unsigned gd_number_of_sections;
508 
509     unsigned gd_map_entry_count;
510 
511     /* A map from section number to group number. */
512     void *gd_map;
513 };
514 
515 struct Dwarf_Debug_s {
516     /*  All file access methods and support data
517         are hidden in this structure.
518         We get a pointer, callers control the lifetime of the
519         structure and contents. */
520     struct Dwarf_Obj_Access_Interface_s *de_obj_file;
521 
522     Dwarf_Handler de_errhand;
523     Dwarf_Ptr de_errarg;
524 
525     /*  Enabling us to close an fd if we own it,
526         as in the case of dwarf_init_path().
527         de_fd is only meaningful
528         if de_owns_fd is set.  Each object
529         file type has any necessary fd recorded
530         under de_obj_file. */
531     int  de_fd;
532     char de_owns_fd;
533     /*  de_path is only set automatically if dwarf_init_path()
534         was used to initialize things.
535         Used with the .gnu_debuglink section. */
536     const char *de_path;
537 
538     const char ** de_gnu_global_paths;
539     unsigned      de_gnu_global_path_count;
540 
541     struct Dwarf_Debug_InfoTypes_s de_info_reading;
542     struct Dwarf_Debug_InfoTypes_s de_types_reading;
543 
544     /*  DW_GROUPNUMBER_ANY, DW_GROUPNUMBER_BASE, DW_GROUPNUMBER_DWO,
545         or a comdat group number > 2
546         Selected at init time of this dbg based on
547         user request and on data in the object. */
548     unsigned de_groupnumber;
549 
550     /* Supporting data for groupnumbers. */
551     struct Dwarf_Group_Data_s de_groupnumbers;
552 
553     /*  Number of bytes in the length, and offset field in various
554         .debu* sections.  It's not very meaningful, and is
555         only used in one 'approximate' calculation.
556         de_offset_size would be a more appropos name. */
557     Dwarf_Small de_length_size;
558 
559     /*  Size of the object file in bytes. If Unknown
560         leave this zero. */
561     Dwarf_Unsigned de_filesize;
562 
563     /*  number of bytes in a pointer of the target in various .debug_
564         sections. 4 in 32bit, 8 in MIPS 64, ia64. */
565     Dwarf_Small de_pointer_size;
566 
567     /*  set at creation of a Dwarf_Debug to say if form_string should be
568         checked for valid length at every call. 0 means do the check.
569         non-zero means do not do the check. */
570     Dwarf_Small de_assume_string_in_bounds;
571 
572     /*  Keep track of allocations so a dwarf_finish call can clean up.
573         Null till a tree is created */
574     void * de_alloc_tree;
575 
576     /*  These fields are used to process debug_frame section.  **Updated
577         by dwarf_get_fde_list in dwarf_frame.h */
578     /*  Points to contiguous block of pointers to Dwarf_Cie_s structs. */
579     Dwarf_Cie *de_cie_data;
580     /*  Count of number of Dwarf_Cie_s structs. */
581     Dwarf_Signed de_cie_count;
582     /*  Keep eh (GNU) separate!. */
583     Dwarf_Cie *de_cie_data_eh;
584     Dwarf_Signed de_cie_count_eh;
585     /*  Points to contiguous block of pointers to Dwarf_Fde_s structs. */
586     Dwarf_Fde *de_fde_data;
587     /*  Count of number of Dwarf_Fde_s structs. */
588     Dwarf_Unsigned de_fde_count;
589     /*  Keep eh (GNU) separate!. */
590     Dwarf_Fde *de_fde_data_eh;
591     Dwarf_Unsigned de_fde_count_eh;
592 
593     struct Dwarf_Section_s de_debug_info;
594     struct Dwarf_Section_s de_debug_types;
595     struct Dwarf_Section_s de_debug_abbrev;
596     struct Dwarf_Section_s de_debug_line;
597     struct Dwarf_Section_s de_debug_line_str; /* New in DWARF5 */
598     struct Dwarf_Section_s de_debug_loc;
599     struct Dwarf_Section_s de_debug_aranges;
600     struct Dwarf_Section_s de_debug_macinfo;
601     struct Dwarf_Section_s de_debug_macro;    /* New in DWARF5 */
602     struct Dwarf_Section_s de_debug_names;    /* New in DWARF5 */
603     struct Dwarf_Section_s de_debug_pubnames;
604     struct Dwarf_Section_s de_debug_str;
605     struct Dwarf_Section_s de_debug_sup;      /* New in DWARF5 */
606     struct Dwarf_Section_s de_debug_loclists; /* New in DWARF5 */
607     struct Dwarf_Section_s de_debug_rnglists; /* New in DWARF5 */
608     struct Dwarf_Section_s de_debug_frame;
609     struct Dwarf_Section_s de_gnu_debuglink;  /* New September 2019 */
610     struct Dwarf_Section_s de_note_gnu_buildid; /* New September 2019 */
611 
612 
613     /* gnu: the g++ eh_frame section */
614     struct Dwarf_Section_s de_debug_frame_eh_gnu;
615 
616     struct Dwarf_Section_s de_debug_pubtypes; /* DWARF3 .debug_pubtypes */
617 
618 
619     /*  Four SGI IRIX extensions essentially
620         identical to DWARF3 .debug_pubtypes.
621         Only on SGI IRIX. */
622     struct Dwarf_Section_s de_debug_funcnames;
623     struct Dwarf_Section_s de_debug_typenames;
624     struct Dwarf_Section_s de_debug_varnames;
625     struct Dwarf_Section_s de_debug_weaknames;
626 
627     struct Dwarf_Section_s de_debug_ranges;
628     /*  Following two part of DebugFission and DWARF5 */
629     struct Dwarf_Section_s de_debug_str_offsets;
630     struct Dwarf_Section_s de_debug_addr;
631 
632     /*  For the .debug_rnglists[.dwo] section */
633     Dwarf_Unsigned de_rnglists_context_count;
634     /*  pointer to array of pointers to
635         rnglists context instances */
636     Dwarf_Rnglists_Context *  de_rnglists_context;
637 
638     /*  For the .debug_loclists[.dwo] section */
639     Dwarf_Unsigned de_loclists_context_count;
640     /*  pointer to array of pointers to
641         loclists context instances */
642     Dwarf_Loclists_Context *  de_loclists_context;
643 
644     /* Following for the .gdb_index section.  */
645     struct Dwarf_Section_s de_debug_gdbindex;
646 
647     /*  Types in DWARF5 are in .debug_info
648         and in DWARF4 are in .debug_types.
649         These indexes first standardized in DWARF5,
650         DWARF4 can have them as an extension.
651         The next to refer to the DWP index sections and the
652         tu and cu indexes sections are distinct in DWARF4 & 5. */
653     struct Dwarf_Section_s de_debug_cu_index;
654     struct Dwarf_Section_s de_debug_tu_index;
655 
656     /*  For non-elf, simply leave the following two structs zeroed and
657         they will be ignored. */
658     struct Dwarf_Section_s de_elf_symtab;
659     struct Dwarf_Section_s de_elf_strtab;
660 
661     /*  For a .dwp object file .
662         For DWARF4, type units are in .debug_types
663             (DWP is a GNU extension in DW4)..
664         For DWARF5, type units are in .debug_info.
665     */
666     Dwarf_Xu_Index_Header  de_cu_hashindex_data;
667     Dwarf_Xu_Index_Header  de_tu_hashindex_data;
668 
669     void (*de_copy_word) (void *, const void *, unsigned long);
670     unsigned char de_same_endian;
671     unsigned char de_elf_must_close; /* If non-zero, then
672         it was dwarf_init (not dwarf_elf_init)
673         so must elf_end() */
674 
675     /* Default is DW_FRAME_INITIAL_VALUE from header. */
676     Dwarf_Half de_frame_rule_initial_value;
677 
678     /* Default is   DW_FRAME_LAST_REG_NUM. */
679     Dwarf_Half de_frame_reg_rules_entry_count;
680 
681     Dwarf_Half de_frame_cfa_col_number;
682     Dwarf_Half de_frame_same_value_number;
683     Dwarf_Half de_frame_undefined_value_number;
684 
685     unsigned char de_big_endian_object; /* Non-zero if
686         object being read is big-endian. */
687 
688     /*  Non-zero if dwarf_get_globals(), dwarf_get_funcs,
689         dwarf_get_types,dwarf_get_pubtypes,
690         dwarf_get_vars,dwarf_get_weaks should create
691         and return a special zero-die-offset for the
692         corresponding pubnames-style section CU header with
693         zero pubnames-style named DIEs.  In that case the
694         list returned will have an entry with a zero for
695         the die-offset (which is an impossible debug_info
696         die_offset). New March 2019.
697         See dwarf_return_empty_pubnames() */
698     unsigned char de_return_empty_pubnames;
699 
700     struct Dwarf_dbg_sect_s de_debug_sections[DWARF_MAX_DEBUG_SECTIONS];
701     unsigned de_debug_sections_total_entries; /* Number actually used. */
702 
703     struct Dwarf_Harmless_s de_harmless_errors;
704 
705     struct Dwarf_Printf_Callback_Info_s  de_printf_callback;
706     void *   de_printf_callback_null_device_handle;
707 
708     /*  Used in a tied dbg  to hold global info
709         on the tied object (DW_AT_dwo_id).
710         And for Type Unit signatures whether tied
711         or not. */
712     struct Dwarf_Tied_Data_s de_tied_data;
713 
714 };
715 
716 /* New style. takes advantage of dwarfstrings capability.
717     This not a public function. */
718 int _dwarf_printf(Dwarf_Debug dbg, const char * data);
719 
720 typedef struct Dwarf_Chain_s *Dwarf_Chain;
721 struct Dwarf_Chain_s {
722     void *ch_item;
723     int  ch_itemtype; /* Needed to dealloc chain contents */
724     Dwarf_Chain ch_next;
725 };
726 
727 typedef struct Dwarf_Chain_o *Dwarf_Chain_2;
728 struct Dwarf_Chain_o {
729     Dwarf_Off ch_item;
730     Dwarf_Chain_2 ch_next;
731 };
732 
733     /* Size of cu header version stamp field. */
734 #define CU_VERSION_STAMP_SIZE   DWARF_HALF_SIZE
735 
736     /* Size of cu header address size field. */
737 #define CU_ADDRESS_SIZE_SIZE    sizeof(Dwarf_Small)
738 
739 #define ORIGINAL_DWARF_OFFSET_SIZE  4
740 /*  The DISTINGUISHED VALUE is 4 byte value defined by DWARF
741     since DWARF3. */
742 #define DISTINGUISHED_VALUE  0xffffffff
743 #define DISTINGUISHED_VALUE_OFFSET_SIZE 8
744 #define DISTINGUISHED_VALUE_ARRAY(x)  char x[4] = { 0xff,0xff,0xff,0xff }
745 
746 
747 int _dwarf_ignorethissection(const char *scn_name);
748 
749 /*  We don't load the sections until they are needed. This function is
750     used to load the section.  */
751 int _dwarf_load_section(Dwarf_Debug,
752     struct Dwarf_Section_s *,
753     Dwarf_Error *);
754 
755 void _dwarf_dealloc_rnglists_context(Dwarf_Debug dbg);
756 void _dwarf_dealloc_loclists_context(Dwarf_Debug dbg);
757 
758 int _dwarf_get_string_base_attr_value(Dwarf_Debug dbg,
759     Dwarf_CU_Context context,
760     Dwarf_Unsigned *sbase_out,
761     Dwarf_Error *error);
762 
763 int _dwarf_extract_string_offset_via_str_offsets(Dwarf_Debug dbg,
764     Dwarf_Small *data_ptr,
765     Dwarf_Small *end_data_ptr,
766     Dwarf_Half   attrnum,
767     Dwarf_Half   attrform,
768     Dwarf_CU_Context cu_context,
769     Dwarf_Unsigned *str_sect_offset_out,
770     Dwarf_Error *error);
771 
772 
773 int _dwarf_extract_address_from_debug_addr(Dwarf_Debug dbg,
774     Dwarf_CU_Context context,
775     Dwarf_Unsigned index,
776     Dwarf_Addr *addr_out,
777     Dwarf_Error *error);
778 
779 int _dwarf_get_base_and_size_given_signature(
780     Dwarf_CU_Context *context,
781     Dwarf_Sig8 *signature_in,
782     /* xu_sect_index means DW_SECT_info etc. */
783     Dwarf_Unsigned xu_sect_index,
784     Dwarf_Unsigned *base_out,
785     Dwarf_Unsigned *size_out,
786     Dwarf_Error *err);
787 
788 Dwarf_Bool _dwarf_file_has_debug_fission_cu_index(Dwarf_Debug dbg);
789 Dwarf_Bool _dwarf_file_has_debug_fission_tu_index(Dwarf_Debug dbg);
790 Dwarf_Bool _dwarf_file_has_debug_fission_index(Dwarf_Debug dbg);
791 
792 /* This should only be called on a CU. Never a TU. */
793 int _dwarf_get_debugfission_for_offset(Dwarf_Debug dbg,
794     Dwarf_Off   offset_wanted,
795     const char *keytype, /* "cu" or "tu" */
796     Dwarf_Debug_Fission_Per_CU *  percu_out,
797     Dwarf_Error *error);
798 
799 /* whichone: must be a valid DW_SECT* macro value. */
800 Dwarf_Unsigned _dwarf_get_dwp_extra_offset(
801     struct Dwarf_Debug_Fission_Per_CU_s* dwp,
802     unsigned whichone, Dwarf_Unsigned * size);
803 
804 /*  This will look into the tied Dwarf_Debug
805     to which should have a skeleton CU DIE
806     and an addr_base and also have the .debug_addr
807     section. */
808 
809 int _dwarf_get_addr_from_tied(Dwarf_Debug dbg,
810     Dwarf_CU_Context context,
811     Dwarf_Unsigned addrindex,
812     Dwarf_Addr *addr_out,
813     Dwarf_Error *error);
814 
815 
816 int _dwarf_get_fission_addition_die(Dwarf_Die die, int dw_sect_index,
817    Dwarf_Unsigned* offset, Dwarf_Unsigned*size,
818    Dwarf_Error *error);
819 
820 int _dwarf_get_addr_index_itself(int theform,
821     Dwarf_Small *info_ptr,
822     Dwarf_Debug dbg,
823     Dwarf_CU_Context cu_context,
824     Dwarf_Unsigned *val_out,
825     Dwarf_Error * error);
826 Dwarf_Bool _dwarf_addr_form_is_indexed(int form);
827 
828 int
829 _dwarf_search_for_signature(Dwarf_Debug dbg,
830    Dwarf_Sig8 sig,
831    Dwarf_CU_Context *context_out,
832    Dwarf_Error *error);
833 
834 
835 void _dwarf_tied_destroy_free_node(void *node);
836 void _dwarf_destroy_group_map(Dwarf_Debug dbg);
837 
838 int _dwarf_section_get_target_group(Dwarf_Debug dbg,
839     unsigned   obj_section_index,
840     unsigned * groupnumber,
841     Dwarf_Error    * error);
842 
843 int _dwarf_dwo_groupnumber_given_name(
844     const char *name,
845     unsigned *grpnum_out);
846 
847 int _dwarf_section_get_target_group_from_map(Dwarf_Debug dbg,
848     unsigned   obj_section_index,
849     unsigned * groupnumber_out,
850     UNUSEDARG Dwarf_Error    * error);
851 
852 int _dwarf_insert_in_group_map(Dwarf_Debug dbg,
853     unsigned groupnum,
854     unsigned section_index,
855     const char *name,
856     Dwarf_Error * error);
857 
858 /* returns TRUE/FALSE: meaning this section name is in
859    map for this groupnum  or not.*/
860 int _dwarf_section_in_group_by_name(Dwarf_Debug dbg,
861     const char * scn_name,
862     unsigned groupnum);
863 
864 int
865 _dwarf_next_cu_header_internal(Dwarf_Debug dbg,
866     Dwarf_Bool is_info,
867     Dwarf_Unsigned * cu_header_length,
868     Dwarf_Half * version_stamp,
869     Dwarf_Unsigned * abbrev_offset,
870     Dwarf_Half * address_size,
871     Dwarf_Half * offset_size,
872     Dwarf_Half * extension_size,
873     Dwarf_Sig8 * signature,
874     Dwarf_Bool * has_signature,
875     Dwarf_Unsigned *typeoffset,
876     Dwarf_Unsigned * next_cu_offset,
877     Dwarf_Half     * header_cu_type,
878     Dwarf_Error * error);
879 
880 /* Relates to .debug_addr */
881 int _dwarf_look_in_local_and_tied(Dwarf_Half attr_form,
882     Dwarf_CU_Context context,
883     Dwarf_Small *info_ptr,
884     Dwarf_Addr *return_addr,
885     Dwarf_Error *error);
886 
887 int _dwarf_get_ranges_base_attr_from_tied(Dwarf_Debug dbg,
888     Dwarf_CU_Context context,
889     Dwarf_Unsigned * ranges_base_out,
890     Dwarf_Unsigned * addr_base_out,
891     Dwarf_Error    * error);
892 
893 int _dwarf_get_string_from_tied(Dwarf_Debug dbg, Dwarf_Unsigned offset,
894     char **return_str, Dwarf_Error*error);
895 
896 int _dwarf_valid_form_we_know(Dwarf_Unsigned at_form,
897     Dwarf_Unsigned at_name);
898 int _dwarf_extract_local_debug_str_string_given_offset(Dwarf_Debug dbg,
899     unsigned attrform,
900     Dwarf_Unsigned offset,
901     char ** return_str,
902     Dwarf_Error *  error);
903 
904 int _dwarf_file_name_is_full_path(Dwarf_Small  *fname);
905 
906 /*  This is an elf-only extension to
907     get SHF_COMPRESSED flag from sh_flags.
908     if pointer not set (which is normal for non-elf objects)
909     it is fine.  */
910 typedef int (*_dwarf_get_elf_flags_func_ptr_type)(
911     void* obj_in,
912     Dwarf_Half section_index,
913     Dwarf_Unsigned *flags_out,
914     Dwarf_Unsigned *addralign_out,
915     int *error);
916 extern _dwarf_get_elf_flags_func_ptr_type _dwarf_get_elf_flags_func_ptr;
917 
918 /* This is libelf access to Elf object. */
919 extern int _dwarf_elf_setup(int fd,
920     char *true_path_out_buffer,
921     unsigned ftype,
922     unsigned endian,
923     unsigned offsetsize,
924     size_t filesize,
925     Dwarf_Unsigned access,
926     unsigned groupnumber,
927     Dwarf_Handler errhand,
928     Dwarf_Ptr errarg,
929     Dwarf_Debug *dbg,Dwarf_Error *error);
930 
931 /*  This is non-libelf Elf access */
932 extern int
933 _dwarf_elf_nlsetup(int fd,
934     char *true_path,
935     unsigned ftype,
936     unsigned endian,
937     unsigned offsetsize,
938     size_t filesize,
939     Dwarf_Unsigned access,
940     unsigned groupnumber,
941     Dwarf_Handler errhand,
942     Dwarf_Ptr errarg,
943     Dwarf_Debug *dbg,Dwarf_Error *error);
944 void _dwarf_destruct_elf_nlaccess(struct Dwarf_Obj_Access_Interface_s *aip);
945 
946 extern int _dwarf_macho_setup(int fd,
947     char *true_path,
948     unsigned ftype,
949     unsigned endian,
950     unsigned offsetsize,
951     size_t filesize,
952     Dwarf_Unsigned access,
953     unsigned groupnumber,
954     Dwarf_Handler errhand,
955     Dwarf_Ptr errarg,
956     Dwarf_Debug *dbg,Dwarf_Error *error);
957 void _dwarf_destruct_macho_access(struct Dwarf_Obj_Access_Interface_s *aip);
958 
959 extern int _dwarf_pe_setup(int fd,
960     char *path,
961     unsigned ftype,
962     unsigned endian,
963     unsigned offsetsize,
964     size_t filesize,
965     Dwarf_Unsigned access,
966     unsigned groupnumber,
967     Dwarf_Handler errhand,
968     Dwarf_Ptr errarg,
969     Dwarf_Debug *dbg,Dwarf_Error *error);
970 void _dwarf_destruct_pe_access(struct Dwarf_Obj_Access_Interface_s *aip);
971 
972 void _dwarf_create_address_size_dwarf_error(Dwarf_Debug dbg,
973     Dwarf_Error *error,
974     Dwarf_Unsigned addrsize,
975     int errcode,const char *errname);
976 
977 
978 extern Dwarf_Bool _dwarf_allow_formudata(unsigned form);
979 extern int _dwarf_formudata_internal(Dwarf_Debug dbg,
980     unsigned form,
981     Dwarf_Byte_Ptr data,
982     Dwarf_Byte_Ptr section_end,
983     Dwarf_Unsigned *return_uval,
984     Dwarf_Unsigned *bytes_read,
985     Dwarf_Error *error);
986 
987 Dwarf_Byte_Ptr _dwarf_calculate_info_section_start_ptr(Dwarf_CU_Context context, Dwarf_Unsigned *section_len_out);
988 
989 Dwarf_Byte_Ptr _dwarf_calculate_info_section_end_ptr(Dwarf_CU_Context context);
990 Dwarf_Byte_Ptr _dwarf_calculate_abbrev_section_end_ptr(Dwarf_CU_Context context);
991 
992 int _dwarf_formblock_internal(Dwarf_Debug dbg,
993     Dwarf_Attribute attr,
994     Dwarf_CU_Context cu_context,
995     Dwarf_Block * return_block,
996     Dwarf_Error * error);
997 
998 int _dwarf_extract_data16(Dwarf_Debug dbg,
999     Dwarf_Small *data,
1000     Dwarf_Small *section_start,
1001     Dwarf_Small *section_end,
1002     Dwarf_Form_Data16  * returned_val,
1003     Dwarf_Error *error);
1004 
1005 
1006 void _dwarf_dumpsig(const char *msg, Dwarf_Sig8 *sig,int lineno);
1007