libdwarf: Rnglists: code addresses in DWARF5

libdwarf

Loading...
Searching...
No Matches
Functions
Rnglists: code addresses in DWARF5

## Functions
DW_API int | dwarf_rnglists_get_rle_head (Dwarf_Attribute dw_attr, Dwarf_Half dw_theform, Dwarf_Unsigned dw_index_or_offset_value, Dwarf_Rnglists_Head *dw_head_out, Dwarf_Unsigned *dw_count_of_entries_in_head, Dwarf_Unsigned *dw_global_offset_of_rle_set, Dwarf_Error *dw_error)
| Get Access to DWARF5 rnglists.
DW_API int | dwarf_get_rnglists_entry_fields_a (Dwarf_Rnglists_Head dw_head, Dwarf_Unsigned dw_entrynum, unsigned int *dw_entrylen, unsigned int *dw_rle_value_out, Dwarf_Unsigned *dw_raw1, Dwarf_Unsigned *dw_raw2, Dwarf_Bool *dw_debug_addr_unavailable, Dwarf_Unsigned *dw_cooked1, Dwarf_Unsigned *dw_cooked2, Dwarf_Error *dw_error)
| Access rnglist entry details.
DW_API void | dwarf_dealloc_rnglists_head (Dwarf_Rnglists_Head dw_head)
| Dealloc a Dwarf_Rnglists_Head.
DW_API int | dwarf_load_rnglists (Dwarf_Debug dw_dbg, Dwarf_Unsigned *dw_rnglists_count, Dwarf_Error *dw_error)
| Loads all .debug_rnglists headers.
DW_API int | dwarf_get_rnglist_offset_index_value (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_context_index, Dwarf_Unsigned dw_offsetentry_index, Dwarf_Unsigned *dw_offset_value_out, Dwarf_Unsigned *dw_global_offset_value_out, Dwarf_Error *dw_error)
| Retrieve the section offset of a rnglist.
DW_API int | dwarf_get_rnglist_head_basics (Dwarf_Rnglists_Head dw_head, Dwarf_Unsigned *dw_rle_count, Dwarf_Unsigned *dw_rnglists_version, Dwarf_Unsigned *dw_rnglists_index_returned, Dwarf_Unsigned *dw_bytes_total_in_rle, Dwarf_Half *dw_offset_size, Dwarf_Half *dw_address_size, Dwarf_Half *dw_segment_selector_size, Dwarf_Unsigned *dw_overall_offset_of_this_context, Dwarf_Unsigned *dw_total_length_of_this_context, Dwarf_Unsigned *dw_offset_table_offset, Dwarf_Unsigned *dw_offset_table_entrycount, Dwarf_Bool *dw_rnglists_base_present, Dwarf_Unsigned *dw_rnglists_base, Dwarf_Bool *dw_rnglists_base_address_present, Dwarf_Unsigned *dw_rnglists_base_address, Dwarf_Bool *dw_rnglists_debug_addr_base_present, Dwarf_Unsigned *dw_rnglists_debug_addr_base, Dwarf_Error *dw_error)
| Access to internal data on rangelists.
DW_API int | dwarf_get_rnglist_context_basics (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_index, Dwarf_Unsigned *dw_header_offset, Dwarf_Small *dw_offset_size, Dwarf_Small *dw_extension_size, unsigned int *dw_version, Dwarf_Small *dw_address_size, Dwarf_Small *dw_segment_selector_size, Dwarf_Unsigned *dw_offset_entry_count, Dwarf_Unsigned *dw_offset_of_offset_array, Dwarf_Unsigned *dw_offset_of_first_rangeentry, Dwarf_Unsigned *dw_offset_past_last_rangeentry, Dwarf_Error *dw_error)
| Access to rnglists header data.
DW_API int | dwarf_get_rnglist_rle (Dwarf_Debug dw_dbg, Dwarf_Unsigned dw_contextnumber, Dwarf_Unsigned dw_entry_offset, Dwarf_Unsigned dw_endoffset, unsigned int *dw_entrylen, unsigned int *dw_entry_kind, Dwarf_Unsigned *dw_entry_operand1, Dwarf_Unsigned *dw_entry_operand2, Dwarf_Error *dw_error)
| Access to raw rnglists range data.

## Detailed Description

Used in DWARF5 to define valid address ranges for code.

DW_FORM_rnglistx or DW_AT_ranges with DW_FORM_sec_offset

## Function Documentation

## ◆ dwarf_dealloc_rnglists_head()

DW_API void dwarf_dealloc_rnglists_head | ( | Dwarf_Rnglists_Head | dw_head | ) |

Dealloc a Dwarf_Rnglists_Head.

Parameters

  dw_head | dealloc all the memory associated with dw_head. The caller should then immediately set the pointer to zero/NULL as it is stale.

## ◆ dwarf_get_rnglist_context_basics()

DW_API int dwarf_get_rnglist_context_basics | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned | dw_index,
|  | Dwarf_Unsigned * | dw_header_offset,
|  | Dwarf_Small * | dw_offset_size,
|  | Dwarf_Small * | dw_extension_size,
|  | unsigned int * | dw_version,
|  | Dwarf_Small * | dw_address_size,
|  | Dwarf_Small * | dw_segment_selector_size,
|  | Dwarf_Unsigned * | dw_offset_entry_count,
|  | Dwarf_Unsigned * | dw_offset_of_offset_array,
|  | Dwarf_Unsigned * | dw_offset_of_first_rangeentry,
|  | Dwarf_Unsigned * | dw_offset_past_last_rangeentry,
|  | Dwarf_Error * | dw_error )

Access to rnglists header data.

This returns, independent of any DIEs or CUs information on the .debug_rnglists headers present in the section.

We do not document the details here. See the DWARF5 standard.

Enables printing of details about the Range List Table Headers, one header per call. Index starting at 0. Returns DW_DLV_NO_ENTRY if index is too high for the table. A .debug_rnglists section may contain any number of Range List Table Headers with their details.

## ◆ dwarf_get_rnglist_head_basics()

DW_API int dwarf_get_rnglist_head_basics | ( | Dwarf_Rnglists_Head | dw_head,
|  | Dwarf_Unsigned * | dw_rle_count,
|  | Dwarf_Unsigned * | dw_rnglists_version,
|  | Dwarf_Unsigned * | dw_rnglists_index_returned,
|  | Dwarf_Unsigned * | dw_bytes_total_in_rle,
|  | Dwarf_Half * | dw_offset_size,
|  | Dwarf_Half * | dw_address_size,
|  | Dwarf_Half * | dw_segment_selector_size,
|  | Dwarf_Unsigned * | dw_overall_offset_of_this_context,
|  | Dwarf_Unsigned * | dw_total_length_of_this_context,
|  | Dwarf_Unsigned * | dw_offset_table_offset,
|  | Dwarf_Unsigned * | dw_offset_table_entrycount,
|  | Dwarf_Bool * | dw_rnglists_base_present,
|  | Dwarf_Unsigned * | dw_rnglists_base,
|  | Dwarf_Bool * | dw_rnglists_base_address_present,
|  | Dwarf_Unsigned * | dw_rnglists_base_address,
|  | Dwarf_Bool * | dw_rnglists_debug_addr_base_present,
|  | Dwarf_Unsigned * | dw_rnglists_debug_addr_base,
|  | Dwarf_Error * | dw_error )

Access to internal data on rangelists.

Returns detailed data from a Dwarf_Rnglists_Head Since this is primarily internal data we don't describe the details of the returned fields here.

## ◆ dwarf_get_rnglist_offset_index_value()

DW_API int dwarf_get_rnglist_offset_index_value | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned | dw_context_index,
|  | Dwarf_Unsigned | dw_offsetentry_index,
|  | Dwarf_Unsigned * | dw_offset_value_out,
|  | Dwarf_Unsigned * | dw_global_offset_value_out,
|  | Dwarf_Error * | dw_error )

Retrieve the section offset of a rnglist.

Can be used to access raw rnglist data. Not used by most callers. See DWARF5 Section 7.28 Range List Table Page 242

Parameters

  dw_dbg | The Dwarf_Debug of interest.
  dw_context_index | Begin this at zero.
  dw_offsetentry_index | Begin this at zero.
  dw_offset_value_out | On success returns the rangelist entry offset within the rangelist set.
  dw_global_offset_value_out | On success returns the rangelist entry offset within rnglist section.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc. If there are no rnglists at all, or if one of the above index values is too high to be valid it returns DW_DLV_NO_ENTRY.

## ◆ dwarf_get_rnglist_rle()

DW_API int dwarf_get_rnglist_rle | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned | dw_contextnumber,
|  | Dwarf_Unsigned | dw_entry_offset,
|  | Dwarf_Unsigned | dw_endoffset,
|  | unsigned int * | dw_entrylen,
|  | unsigned int * | dw_entry_kind,
|  | Dwarf_Unsigned * | dw_entry_operand1,
|  | Dwarf_Unsigned * | dw_entry_operand2,
|  | Dwarf_Error * | dw_error )

Access to raw rnglists range data.

Describes the actual raw data recorded in a particular range entry.

We do not describe all these fields for now, the raw values are mostly useful for people debugging compiler-generated DWARF.

## ◆ dwarf_get_rnglists_entry_fields_a()

DW_API int dwarf_get_rnglists_entry_fields_a | ( | Dwarf_Rnglists_Head | dw_head,
|  | Dwarf_Unsigned | dw_entrynum,
|  | unsigned int * | dw_entrylen,
|  | unsigned int * | dw_rle_value_out,
|  | Dwarf_Unsigned * | dw_raw1,
|  | Dwarf_Unsigned * | dw_raw2,
|  | Dwarf_Bool * | dw_debug_addr_unavailable,
|  | Dwarf_Unsigned * | dw_cooked1,
|  | Dwarf_Unsigned * | dw_cooked2,
|  | Dwarf_Error * | dw_error )

Access rnglist entry details.

See also
  Accessing rnglists section

Parameters

  dw_head | The Dwarf_Rnglists_Head of interest.
  dw_entrynum | Valid values are 0 through dw_count_of_entries_in_head-1.
  dw_entrylen | On success returns the length in bytes of this individual entry.
  dw_rle_value_out | On success returns the RLE value of the entry, such as DW_RLE_startx_endx. This determines which of dw_raw1 and dw_raw2 contain meaningful data.
  dw_raw1 | On success returns a value directly recorded in the rangelist entry if that applies to this rle.
  dw_raw2 | On success returns a value directly recorded in the rangelist entry if that applies to this rle.
  dw_debug_addr_unavailable | On success returns a flag. If the .debug_addr section is required but absent or unavailable the flag is set to TRUE. Otherwise sets the flag FALSE.
  dw_cooked1 | On success returns (if appropriate) the dw_raw1 value turned into a valid address.
  dw_cooked2 | On success returns (if appropriate) the dw_raw2 value turned into a valid address. Ignore the value if dw_debug_addr_unavailable is set.
  dw_error | The usual error detail return pointer. Ignore the value if dw_debug_addr_unavailable is set.

Returns
  Returns DW_DLV_OK etc.

## ◆ dwarf_load_rnglists()

DW_API int dwarf_load_rnglists | ( | Dwarf_Debug | dw_dbg,
|  | Dwarf_Unsigned * | dw_rnglists_count,
|  | Dwarf_Error * | dw_error )

Loads all .debug_rnglists headers.

Loads all the rnglists headers and returns DW_DLV_NO_ENTRY if the section is missing or empty. Intended to be done quite early. It is automatically done if anything needing CU or DIE information is called, so it is not necessary for you to call this in any normal situation.

See also
  Accessing accessing raw rnglist

Doing it more than once is never necessary or harmful. There is no deallocation call made visible, deallocation happens when dwarf_finish() is called.

Parameters

  dw_dbg |
  dw_rnglists_count | On success it returns the number of rnglists headers in the section through dw_rnglists_count.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc. If the section does not exist the function returns DW_DLV_OK.

## ◆ dwarf_rnglists_get_rle_head()

DW_API int dwarf_rnglists_get_rle_head | ( | Dwarf_Attribute | dw_attr,
|  | Dwarf_Half | dw_theform,
|  | Dwarf_Unsigned | dw_index_or_offset_value,
|  | Dwarf_Rnglists_Head * | dw_head_out,
|  | Dwarf_Unsigned * | dw_count_of_entries_in_head,
|  | Dwarf_Unsigned * | dw_global_offset_of_rle_set,
|  | Dwarf_Error * | dw_error )

Get Access to DWARF5 rnglists.

Opens a Dwarf_Rnglists_Head to access a set of DWARF5 rangelists .debug_rnglists DW_FORM_sec_offset DW_FORM_rnglistx (DW_AT_ranges in DWARF5).

See also
  Accessing rnglists section

Parameters

  dw_attr | The attribute referring to .debug_rnglists
  dw_theform | The form number, DW_FORM_sec_offset or DW_FORM_rnglistx.
  dw_index_or_offset_value | If the form is an index, pass it here. If the form is an offset, pass that here.
  dw_head_out | On success creates a record owning the rnglists data for this attribute.
  dw_count_of_entries_in_head | On success this is set to the number of entry in the rnglists for this attribute.
  dw_global_offset_of_rle_set | On success set to the global offset of the rnglists in the rnglists section.
  dw_error | The usual error detail return pointer.

Returns
  Returns DW_DLV_OK etc.