DWARF 5 and Split DWARF Updates to CDA

DIE-query consumer operations

Add new API:

- dwarf_get_dwo_dbg
The dwarf_get_dwo_dbg operation returns the libdwarf consumer instance for the .dwo file associated with the given skeleton root DIE.

--------------------------------------------

dwarf_get_dwo_dbg operation

The dwarf_get_dwo_dbg operation returns the libdwarf consumer instance for the .dwo file associated with the given skeleton root DIE.  The caller should not deallocate the returned libdwarf consumer instance.

Prototype
int dwarf_get_dwo_dbg(
   Dwarf_Die           root_die,
   Dwarf_Debug*        ret_dwo_dbg,
   Dwarf_Error*        error);

Parameters
root_die
   Input. This accepts a skeleton root DIE object.
ret_dwo_dbg
   Output. This returns the libdwarf consumer instance for the .dwo file
error
   Input/output. This accepts or returns the Dwarf_Error object.

Return values
DW_DLV_OK
   A valid libdwarf consumer instance for the .dwo file is returned.
DW_DLV_NO_ENTRY
   The given DIE is not a skeleton root DIE with a valid .dwo file
DW_DLV_ERROR
   Returned if either of the following conditions apply:
       - The given root_die is NULL.
       - The given ret_dwo_dbg is NULL.

=======================================================================
Initialization and termination consumer operations

Add new API after dwarf_goff_init_with_PO_filename:

- dwarf_goff_init_with_GOFF_filename
Given a GOFF object filename, this API creates and initializes a libdwarf consumer instance.  This can be used for a .dwo file when the libdwarf consumer instance for the skeleton unit is not available.

--------------------------------------------

dwarf_goff_init_with_GOFF_filename operation

Given a GOFF object filename, this API creates and initializes a libdwarf consumer instance.  This can be used for a .dwo file when the libdwarf consumer instance for the skeleton unit is not available.

Prototype
int
 dwarf_goff_init_with_GOFF_filename (
   char*                 filename,
   Dwarf_Handler         errhand,
   Dwarf_Ptr             errarg,
   Dwarf_Addr            ccode_addr,
   Dwarf_Debug*          ret_dbg,
   Dwarf_Error*          error);

Parameters
filename
   Input. GOFF object file name. It must be encoded in IBM-1047.
errhand
   Input. NULL if the default error handler is used.
errarg
   Input. When an error condition is triggered within any of the DWARF consumer operations, the errhand parameter accepts this object.
code_addr
   Input. A real C_CODE address used for relocating all address related to C_CODE 
ret_dbg
   Output. libdwarf consumer instance.
error
   Error. This accepts or returns a Dwarf_Error object.

Return values
DW_DLV_OK
   A valid libdwarf consumer instance is returned. 
DW_DLV_NO_ENTRY
   Unable to initialize binder API
   DWARF debug sections are not present in the given GOFF object. 
DW_DLV_ERROR
   DW_DLE_RETURN_PTR_NULL
       Given 'ret_dbg' is NULL
   DW_DLE_DBG_ALLOC
       Unable to allocate memory for *ret_dbg
   DW_DLE_ALLOC_FAIL
       Unable to allocate memory for internal objects 
   DW_DLE_FNO
       Unable to open filename.
   DW_DLE_NOB
       filename is 0 length or it is not a valid GOFF object.
   DW_DLE_FNR
       Input filename contains invalid characters.
   DW_DLE_CANNOT_FIND_FULLPATH
       Unable to determine absolute path for filename. Make sure all paths leading to filename have read and execute permission set. 
   DW_DLE_PROGRAM_OBECT_EDIT_NO
       The program object is bound with EDIT=NO. 
   DW_DLE_PROGRAM_OBJECT_PROCESS_ERROR
       Unable to process the input program object.

Cleanups
Dwarf_Debug dbg;
dwarf_goff_init_with_GOFF_filename ("a.dwo", ..., &dbg, &err); 
... 
// terminate 'dbg' 
dwarf_finish (dbg, error);

Note: To simplify the example, only the relevant parameters are found in the above code. Unlisted parameters are represented by ellipses(...).

=======================================================================
=======================================================================






DWARF expressions
=======================================================================
Location expression operations -> dwarf_get_loc_list_given_offset operation

Change all occurrences of:

".debug_loc"
to
".debug_loc or .debug_loclists"

=======================================================================
Location expression operations

Add new API:

- dwarf_get_loc_list_given_index
The dwarf_get_loc_list_given_index operation decodes location list given an index within .debug_loclists. The order of expression locations returned is in the same order as the encoded information in .debug_loclists.

--------------------------------------------

dwarf_get_loc_list_given_index operation

The dwarf_get_loc_list_given_index operation decodes location list given an offset within .debug_loclists. The order of expression locations returned is in the same order as the encoded information in .debug_loclists.

Prototype
int dwarf_get_loc_list_given_index (
   Dwarf_Debug         dbg,
   Dwarf_Unsigned      index,
   Dwarf_Locdesc***    ret_llbuf,
   Dwarf_Signed *      ret_listlen,
   Dwarf_Off*          ret_off,
   Dwarf_Off*          ret_nextoff,
   Dwarf_Error*        error);

Parameters
dbg
   Input. libdwarf consumer instance.
index
   Input. Index within .debug_loclists.
ret_llbuf
   Output. An array of Dwarf_Locdesc* objects.
ret_listlen
   Output. Number of Dwarf_Locdesc* objects in the array.
ret_off
   Output. The offset to the beginning of this location list. This field can be NULL, in which case, this value will not be used.
ret_nextoff
   Output. The offset to the beginning of the next location list. This field can be NULL, in which case, this value will not be used.
error
   Input/output. This accepts or returns the Dwarf_Error object.

Return values
DW_DLV_OK
   An array of Dwarf_Locdesc* object is returned.
DW_DLV_NO_ENTRY
       .debug_loclists debug section does not exist or is empty.
       .debug_info debug section does not exist or is empty.
DW_DLV_ERROR
   Returned if either of the following conditions apply:
       The given dbg is NULL.
       Unable to determine the offset of the next location list entry.
       Unable to allocate memory for creating internal objects.

Cleanups
Dwarf_Locdesc** loclist;
Dwarf_Signed    loclist_n;

dwarf_get_loc_list_given_index (dbg, index, &loclist, &loclist_n, NULL, NULL, &err);

for (i=0; i<loclist_n; i++) {
 dwarf_dealloc (dbg, loclist[i]->ld_s, DW_DLA_LOC_BLOCK);
 dwarf_dealloc (dbg, loclist[i], DW_DLA_LOCDESC);
}
dwarf_dealloc (dbg, loclist, DW_DLA_LIST);
=======================================================================