diff options
Diffstat (limited to 'rtemstoolkit/elftoolchain/libdwarf/dwarf_get_ranges.3')
| -rw-r--r-- | rtemstoolkit/elftoolchain/libdwarf/dwarf_get_ranges.3 | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/rtemstoolkit/elftoolchain/libdwarf/dwarf_get_ranges.3 b/rtemstoolkit/elftoolchain/libdwarf/dwarf_get_ranges.3 new file mode 100644 index 0000000..15bad4d --- /dev/null +++ b/rtemstoolkit/elftoolchain/libdwarf/dwarf_get_ranges.3 @@ -0,0 +1,258 @@ +.\" Copyright (c) 2011 Kai Wang +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $Id: dwarf_get_ranges.3 3182 2015-04-10 16:08:10Z emaste $ +.\" +.Dd November 9, 2011 +.Os +.Dt DWARF_GET_RANGES 3 +.Sh NAME +.Nm dwarf_get_ranges +.Nd retrieve non-contiguous address ranges +.Sh LIBRARY +.Lb libdwarf +.Sh SYNOPSIS +.In libdwarf.h +.Ft int +.Fo dwarf_get_ranges +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Ranges **ranges" +.Fa "Dwarf_Signed *cnt" +.Fa "Dwarf_Unsigned *byte_cnt" +.Fa "Dwarf_Error *err" +.Fc +.Ft int +.Fo dwarf_get_ranges_a +.Fa "Dwarf_Debug dbg" +.Fa "Dwarf_Off offset" +.Fa "Dwarf_Die die" +.Fa "Dwarf_Ranges **ranges" +.Fa "Dwarf_Signed *cnt" +.Fa "Dwarf_Unsigned *byte_cnt" +.Fa "Dwarf_Error *err" +.Fc +.Sh DESCRIPTION +Function +.Fn dwarf_get_ranges +retrieves information about the non-contiguous address ranges associated +with a DWARF debugging information entry. +Information about address ranges is returned as an array of +descriptors of type +.Vt Dwarf_Ranges , +with each +.Vt Dwarf_Ranges +descriptor describing one address range entry. +.Pp +Argument +.Ar dbg +should reference a DWARF debug context allocated using +.Xr dwarf_init 3 . +.Pp +Argument +.Ar offset +is an offset, relative to the +.Dq ".debug_ranges" +section, to the start of the desired list of address ranges. +The offset of an address ranges list is indicated by the +.Dv DW_AT_ranges +attribute of a debugging information entry. +.Pp +Argument +.Ar die +(function +.Fn dwarf_get_ranges_a +only) is ignored in this implementation; see the section +.Sx "Compatibility Notes" +below. +.Pp +Argument +.Ar ranges +should point to a location that will be set to a pointer to an array +of +.Vt Dwarf_Ranges +descriptors. +.Pp +Argument +.Ar cnt +should point to a location that will be set to the number of entries +returned. +If argument +.Ar byte_cnt +is not NULL, it will be set to the number of bytes occupied by the +returned entries in the +.Dq ".debug_ranges" +section. +.Pp +If argument +.Ar err +is not NULL, it will be used to store error information in case +of an error. +.Pp +.Vt Dwarf_Ranges +descriptors are defined in the header file +.In libdwarf.h , +and consists of the following fields: +.Bl -tag -width ".Va dwr_addr1" +.It Va dwr_addr1 +The first address offset, whose meaning depends on the type of the +entry. +.It Va dwr_addr2 +The second address offset, whose meaning depends on the type of the +entry. +.It Va dwr_type +The type of this address range entry: +.Bl -tag -width ".Dv DW_RANGES_ENTRY" -compact +.It Dv DW_RANGES_ENTRY +A range list entry. +For this type of entry, the fields +.Va dwr_addr1 +and +.Va dwr_addr2 +hold the beginning and ending offsets of the address range, respectively. +.It Dv DW_RANGES_ADDRESS_SELECTION +A base address selection entry. +For this type of entry, the field +.Va dwr_addr1 +is the value of the largest representable address offset, and +.Va dwr_addr2 +is a base address for the beginning and ending address offsets of +subsequent address range entries in the list. +.It Dv DW_RANGES_END +An end of list mark. +Both +.Va dwr_addr1 +and +.Va dwr_addr2 +are set to 0. +.El +.El +.Ss Memory Management +The memory area used for the array of +.Vt Dwarf_Ranges +descriptors returned in argument +.Ar ranges +is owned by the +.Lb libdwarf . +The application should not attempt to directly free this pointer. +Portable code should instead use +.Fn dwarf_ranges_dealloc +to indicate that the memory may be freed. +.Sh COMPATIBILITY +Function +.Fn dwarf_get_ranges_a +is identical to +.Fn dwarf_get_ranges , +except that it requires one additional argument +.Ar die +denoting the debugging information entry associated with +the address range list. +In this implementation of the +.Lb libdwarf , +the argument +.Ar die +is ignored, and function +.Fn dwarf_get_ranges_a +is only provided for compatibility with other implementations of the +DWARF(3) API. +.Sh RETURN VALUES +These functions +return +.Dv DW_DLV_OK +when they succeed. +They return +.Dv DW_DLV_NO_ENTRY +if there is no address range list at the specified offset +.Ar offset . +In case of an error, they return +.Dv DW_DLV_ERROR +and set the argument +.Ar err . +.Sh ERRORS +These function can fail with: +.Bl -tag -width ".Bq Er DW_DLE_NO_ENTRY" +.It Bq Er DW_DLE_ARGUMENT +One of the arguments +.Ar dbg , +.Ar ranges +or +.Ar cnt +was NULL. +.It Bq Er DW_DLE_NO_ENTRY +There is no address range list at the specified offset +.Ar offset . +.El +.Sh EXAMPLE +To retrieve the address range list associated with a debugging +information entry, use: +.Bd -literal -offset indent +Dwarf_Debug dbg; +Dwarf_Die die; +Dwarf_Error de; +Dwarf_Addr base; +Dwarf_Attribute *attr_list; +Dwarf_Ranges *ranges; +Dwarf_Signed cnt; +Dwarf_Unsigned off, attr_count, bytecnt; +int i, j; + +if ((ret = dwarf_attrlist(die, &attr_list, &attr_count, &de)) != + DW_DLV_OK) + errx(EXIT_FAILURE, "dwarf_attrlist failed: %s", + dwarf_errmsg(de)); + +for (i = 0; (Dwarf_Unsigned) i < attr_count; i++) { + if (dwarf_whatattr(attr_list[i], &attr, &de) != DW_DLV_OK) { + warnx("dwarf_whatattr failed: %s", + dwarf_errmsg(de)); + continue; + } + if (attr != DW_AT_ranges) + continue; + if (dwarf_formudata(attr_list[i], &off, &de) != DW_DLV_OK) { + warnx("dwarf_formudata failed: %s", + dwarf_errmsg(de)); + continue; + } + if (dwarf_get_ranges(dbg, (Dwarf_Off) off, &ranges, &cnt, + &bytecnt, &de) != DW_DLV_OK) + continue; + for (j = 0; j < cnt; j++) { + if (ranges[j].dwr_type == DW_RANGES_END) + break; + else if (ranges[j].dwr_type == + DW_RANGES_ADDRESS_SELECTION) + base = ranges[j].dwr_addr2; + else { + /* + * DW_RANGES_ENTRY entry. + * .. Use dwr_addr1 and dwr_addr2 .. + */ + } + } +} +.Ed +.Sh SEE ALSO +.Xr dwarf 3 , +.Xr dwarf_ranges_dealloc 3 |