1cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Interfaces for libdwfl. 2cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Copyright (C) 2005, 2006, 2007, 2008 Red Hat, Inc. 3cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This file is part of Red Hat elfutils. 4cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 5cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Red Hat elfutils is free software; you can redistribute it and/or modify 6cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng it under the terms of the GNU General Public License as published by the 7cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Free Software Foundation; version 2 of the License. 8cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 9cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Red Hat elfutils is distributed in the hope that it will be useful, but 10cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng WITHOUT ANY WARRANTY; without even the implied warranty of 11cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng General Public License for more details. 13cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 14cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng You should have received a copy of the GNU General Public License along 15cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng with Red Hat elfutils; if not, write to the Free Software Foundation, 16cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA. 17cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 18cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng In addition, as a special exception, Red Hat, Inc. gives You the 19cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng additional right to link the code of Red Hat elfutils with code licensed 20cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng under any Open Source Initiative certified open source license 21cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng (http://www.opensource.org/licenses/index.php) which requires the 22cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng distribution of source code with any binary distribution and to 23cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng distribute linked combinations of the two. Non-GPL Code permitted under 24cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng this exception must only link to the code of Red Hat elfutils through 25cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng those well defined interfaces identified in the file named EXCEPTION 26cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng found in the source code files (the "Approved Interfaces"). The files 27cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng of Non-GPL Code may instantiate templates or use macros or inline 28cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng functions from the Approved Interfaces without causing the resulting 29cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng work to be covered by the GNU General Public License. Only Red Hat, 30cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Inc. may make changes or additions to the list of Approved Interfaces. 31cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Red Hat's grant of this exception is conditioned upon your not adding 32cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng any new exceptions. If you wish to add a new Approved Interface or 33cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng exception, please contact Red Hat. You must obey the GNU General Public 34cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng License in all respects for all of the Red Hat elfutils code and other 35cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng code used in conjunction with Red Hat elfutils except the Non-GPL Code 36cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng covered by this exception. If you modify this file, you may extend this 37cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng exception to your version of the file, but you are not obligated to do 38cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng so. If you do not wish to provide this exception without modification, 39cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng you must delete this exception statement from your version and license 40cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng this file solely under the GPL without exception. 41cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 42cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Red Hat elfutils is an included package of the Open Invention Network. 43cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng An included package of the Open Invention Network is a package for which 44cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Open Invention Network licensees cross-license their patents. No patent 45cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng license is granted, either expressly or impliedly, by designation as an 46cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng included package. Should you wish to participate in the Open Invention 47cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Network licensing program, please visit www.openinventionnetwork.com 48cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng <http://www.openinventionnetwork.com>. */ 49cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 50cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#ifndef _LIBDWFL_H 51cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#define _LIBDWFL_H 1 52cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 53cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#include "libdw.h" 54cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#include <stdio.h> 55cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 56cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Handle for a session using the library. */ 57cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengtypedef struct Dwfl Dwfl; 58cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 59cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Handle for a module. */ 60cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengtypedef struct Dwfl_Module Dwfl_Module; 61cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 62cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Handle describing a line record. */ 63cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengtypedef struct Dwfl_Line Dwfl_Line; 64cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 65cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Callbacks. */ 66cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengtypedef struct 67cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng{ 68cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*find_elf) (Dwfl_Module *mod, void **userdata, 69cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *modname, Dwarf_Addr base, 70cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **file_name, Elf **elfp); 71cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 72cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*find_debuginfo) (Dwfl_Module *mod, void **userdata, 73cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *modname, Dwarf_Addr base, 74cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *file_name, 75cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *debuglink_file, GElf_Word debuglink_crc, 76cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **debuginfo_file_name); 77cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 78cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng /* Fill *ADDR with the loaded address of the section called SECNAME in 79cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng the given module. Use (Dwarf_Addr) -1 if this section is omitted from 80cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng accessible memory. This is called exactly once for each SHF_ALLOC 81cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng section that relocations affecting DWARF data refer to, so it can 82cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng easily be used to collect state about the sections referenced. */ 83cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*section_address) (Dwfl_Module *mod, void **userdata, 84cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *modname, Dwarf_Addr base, 85cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *secname, 86cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Word shndx, const GElf_Shdr *shdr, 87cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *addr); 88cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 89cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **debuginfo_path; /* See dwfl_standard_find_debuginfo. */ 90cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng} Dwfl_Callbacks; 91cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 92cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 93cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#ifdef __cplusplus 94cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern "C" { 95cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#endif 96cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 97cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Start a new session with the library. */ 98cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl *dwfl_begin (const Dwfl_Callbacks *callbacks) 99cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (1); 100cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 101cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 102cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* End a session. */ 103cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern void dwfl_end (Dwfl *); 104cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 105cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return implementation's version string suitable for printing. */ 106cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_version (Dwfl *); 107cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 108cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return error code of last failing function call. This value is kept 109cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng separately for each thread. */ 110cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_errno (void); 111cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 112cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return error string for ERROR. If ERROR is zero, return error string 113cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng for most recent error or NULL if none occurred. If ERROR is -1 the 114cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng behaviour is similar to the last case except that not NULL but a legal 115cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng string is returned. */ 116cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_errmsg (int err); 117cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 118cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 119cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Start reporting the current set of segments and modules to the library. 120cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng All existing segments are wiped. Existing modules are marked to be 121cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng deleted, and will not be found via dwfl_addrmodule et al if they are not 122cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng re-reported before dwfl_report_end is called. */ 123cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern void dwfl_report_begin (Dwfl *dwfl); 124cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 125cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Report that segment NDX begins at PHDR->p_vaddr + BIAS. 126cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If NDX is < 0, the value succeeding the last call's NDX 127cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng is used instead (zero on the first call). 128cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 129cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If nonzero, the smallest PHDR->p_align value seen sets the 130cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng effective page size for the address space DWFL describes. 131cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This is the granularity at which reported module boundary 132cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng addresses will be considered to fall in or out of a segment. 133cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 134cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns -1 for errors, or NDX (or its assigned replacement) on success. 135cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 136cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng When NDX is the value succeeding the last call's NDX (or is implicitly 137cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng so as above), IDENT is nonnull and matches the value in the last call, 138cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and the PHDR and BIAS values reflect a segment that would be contiguous, 139cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng in both memory and file, with the last segment reported, then this 140cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng segment may be coalesced internally with preceding segments. When given 141cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng an address inside this segment, dwfl_addrsegment may return the NDX of a 142cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng preceding contiguous segment. To prevent coalesced segments, always 143cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng pass a null pointer for IDENT. 144cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 145cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng The values passed are not stored (except to track coalescence). 146cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng The only information that can be extracted from DWFL later is the 147cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng mapping of an address to a segment index that starts at or below 148cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng it. Reporting segments at all is optional. Its only benefit to 149cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng the caller is to offer this quick lookup via dwfl_addrsegment, 150cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or use other segment-based calls. */ 151cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_report_segment (Dwfl *dwfl, int ndx, 152cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const GElf_Phdr *phdr, GElf_Addr bias, 153cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const void *ident); 154cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 155cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Report that a module called NAME spans addresses [START, END). 156cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns the module handle, either existing or newly allocated, 157cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or returns a null pointer for an allocation error. */ 158cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_report_module (Dwfl *dwfl, const char *name, 159cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr start, Dwarf_Addr end); 160cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 161cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Report a module with start and end addresses computed from the ELF 162cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng program headers in the given file, plus BASE. For an ET_REL file, 163cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng does a simple absolute section layout starting at BASE. 164cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng FD may be -1 to open FILE_NAME. On success, FD is consumed by the 165cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng library, and the `find_elf' callback will not be used for this module. */ 166cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_report_elf (Dwfl *dwfl, const char *name, 167cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *file_name, int fd, 168cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Addr base); 169cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 170cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Similar, but report the module for offline use. All ET_EXEC files 171cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng being reported must be reported before any relocatable objects. 172cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If this is used, dwfl_report_module and dwfl_report_elf may not be 173cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng used in the same reporting session. */ 174cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_report_offline (Dwfl *dwfl, const char *name, 175cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *file_name, int fd); 176cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 177cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 178cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Finish reporting the current set of modules to the library. 179cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If REMOVED is not null, it's called for each module that 180cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng existed before but was not included in the current report. 181cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns a nonzero return value from the callback. 182cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng The callback may call dwfl_report_module; doing so with the 183cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng details of the module being removed prevents its removal. 184cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng DWFL cannot be used until this function has returned zero. */ 185cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_report_end (Dwfl *dwfl, 186cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*removed) (Dwfl_Module *, void *, 187cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 188cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg), 189cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg); 190cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 191cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Start reporting additional modules to the library. No calls but 192cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng dwfl_report_* can be made on DWFL until dwfl_report_end is called. 193cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This is like dwfl_report_begin, but all the old modules are kept on. 194cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng More dwfl_report_* calls can follow to add more modules. 195cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng When dwfl_report_end is called, no old modules will be removed. */ 196cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern void dwfl_report_begin_add (Dwfl *dwfl); 197cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 198cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 199cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the name of the module, and for each non-null argument store 200cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng interesting details: *USERDATA is a location for storing your own 201cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng pointer, **USERDATA is initially null; *START and *END give the address 202cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng range covered by the module; *DWBIAS is the address bias for debugging 203cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng information, and *SYMBIAS for symbol table entries (either is -1 if not 204cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng yet accessed); *MAINFILE is the name of the ELF file, and *DEBUGFILE the 205cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng name of the debuginfo file (might be equal to *MAINFILE; either is null 206cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if not yet accessed). */ 207cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_module_info (Dwfl_Module *mod, void ***userdata, 208cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *start, Dwarf_Addr *end, 209cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *dwbias, Dwarf_Addr *symbias, 210cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char **mainfile, 211cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char **debugfile); 212cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 213cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Iterate through the modules, starting the walk with OFFSET == 0. 214cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Calls *CALLBACK for each module as long as it returns DWARF_CB_OK. 215cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng When *CALLBACK returns another value, the walk stops and the 216cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng return value can be passed as OFFSET to resume it. Returns 0 when 217cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng there are no more modules, or -1 for errors. */ 218cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern ptrdiff_t dwfl_getmodules (Dwfl *dwfl, 219cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*callback) (Dwfl_Module *, void **, 220cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 221cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg), 222cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg, 223cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng ptrdiff_t offset); 224cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 225cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the module containing the given address. */ 226cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_addrmodule (Dwfl *dwfl, Dwarf_Addr address); 227cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 228cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the segment, if any, and module, if any, containing ADDRESS. 229cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns a segment index returned by dwfl_report_segment, or -1 230cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if no segment matches the address. Regardless of the return value, 231cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng *MOD is always set to the module containing ADDRESS, or to null. */ 232cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_addrsegment (Dwfl *dwfl, Dwarf_Addr address, Dwfl_Module **mod); 233cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 234cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 235cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 236cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Report the known build ID bits associated with a module. 237cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If VADDR is nonzero, it gives the absolute address where those 238cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng bits are found within the module. This can be called at any 239cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng time, but is usually used immediately after dwfl_report_module. 240cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Once the module's main ELF file is opened, the ID note found 241cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng there takes precedence and cannot be changed. */ 242cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_report_build_id (Dwfl_Module *mod, 243cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const unsigned char *bits, size_t len, 244cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Addr vaddr) 245cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (2); 246cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 247cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Extract the build ID bits associated with a module. 248cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns -1 for errors, 0 if no ID is known, or the number of ID bytes. 249cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng When an ID is found, *BITS points to it; *VADDR is the absolute address 250cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng at which the ID bits are found within the module, or 0 if unknown. 251cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 252cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This returns 0 when the module's main ELF file has not yet been loaded 253cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and its build ID bits were not reported. To ensure the ID is always 254cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng returned when determinable, call dwfl_module_getelf first. */ 255cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_build_id (Dwfl_Module *mod, 256cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const unsigned char **bits, GElf_Addr *vaddr) 257cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (2, 3); 258cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 259cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 260cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/*** Standard callbacks ***/ 261cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 262cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* These standard find_elf and find_debuginfo callbacks are 263cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng controlled by a string specifying directories to look in. 264cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If `debuginfo_path' is set in the Dwfl_Callbacks structure 265cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and the char * it points to is not null, that supplies the 266cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng string. Otherwise a default path is used. 267cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 268cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If the first character of the string is + or - that enables or 269cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng disables CRC32 checksum validation when it's necessary. The 270cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng remainder of the string is composed of elements separated by 271cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng colons. Each element can start with + or - to override the 272cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng global checksum behavior. This flag is never relevant when 273cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng working with build IDs, but it's always parsed in the path 274cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng string. The remainder of the element indicates a directory. 275cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 276cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Searches by build ID consult only the elements naming absolute 277cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng directory paths. They look under those directories for a link 278cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng named ".build-id/xx/yy" or ".build-id/xx/yy.debug", where "xxyy" 279cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng is the lower-case hexadecimal representation of the ID bytes. 280cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 281cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng In searches for debuginfo by name, if the remainder of the 282cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng element is empty, the directory containing the main file is 283cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng tried; if it's an absolute path name, the absolute directory path 284cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng containing the main file is taken as a subdirectory of this path; 285cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng a relative path name is taken as a subdirectory of the directory 286cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng containing the main file. Hence for /bin/ls, the default string 287cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng ":.debug:/usr/lib/debug" says to look in /bin, then /bin/.debug, 288cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng then /usr/lib/debug/bin, for the file name in the .gnu_debuglink 289cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng section (or "ls.debug" if none was found). */ 290cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 291cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Standard find_elf callback function working solely on build ID. 292cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This can be tried first by any find_elf callback, to use the 293cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng bits passed to dwfl_module_report_build_id, if any. */ 294cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_build_id_find_elf (Dwfl_Module *, void **, 295cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 296cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **, Elf **); 297cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 298cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Standard find_debuginfo callback function working solely on build ID. 299cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This can be tried first by any find_debuginfo callback, 300cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng to use the build ID bits from the main file when present. */ 301cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_build_id_find_debuginfo (Dwfl_Module *, void **, 302cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 303cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, const char *, 304cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Word, char **); 305cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 306cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Standard find_debuginfo callback function. 307cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If a build ID is available, this tries first to use that. 308cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If there is no build ID or no valid debuginfo found by ID, 309cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng it searches the debuginfo path by name, as described above. 310cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Any file found in the path is validated by build ID if possible, 311cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or else by CRC32 checksum if enabled, and skipped if it does not match. */ 312cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_standard_find_debuginfo (Dwfl_Module *, void **, 313cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 314cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, const char *, 315cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Word, char **); 316cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 317cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 318cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* This callback must be used when using dwfl_offline_* to report modules, 319cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if ET_REL is to be supported. */ 320cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_offline_section_address (Dwfl_Module *, void **, 321cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 322cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, GElf_Word, 323cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const GElf_Shdr *, 324cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *addr); 325cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 326cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 327cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Callbacks for working with kernel modules in the running Linux kernel. */ 328cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_kernel_find_elf (Dwfl_Module *, void **, 329cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 330cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **, Elf **); 331cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_kernel_module_section_address (Dwfl_Module *, void **, 332cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 333cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, GElf_Word, 334cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const GElf_Shdr *, 335cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *addr); 336cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 337cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Call dwfl_report_elf for the running Linux kernel. 338cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero on success, -1 if dwfl_report_module failed, 339cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or an errno code if opening the kernel binary failed. */ 340cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_kernel_report_kernel (Dwfl *dwfl); 341cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 342cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Call dwfl_report_module for each kernel module in the running Linux kernel. 343cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero on success, -1 if dwfl_report_module failed, 344cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or an errno code if reading the list of modules failed. */ 345cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_kernel_report_modules (Dwfl *dwfl); 346cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 347cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Report a kernel and its modules found on disk, for offline use. 348cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If RELEASE starts with '/', it names a directory to look in; 349cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if not, it names a directory to find under /lib/modules/; 350cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if null, /lib/modules/`uname -r` is used. 351cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero on success, -1 if dwfl_report_module failed, 352cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or an errno code if finding the files on disk failed. 353cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 354cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If PREDICATE is not null, it is called with each module to be reported; 355cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng its arguments are the module name, and the ELF file name or null if unknown, 356cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and its return value should be zero to skip the module, one to report it, 357cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or -1 to cause the call to fail and return errno. */ 358cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_kernel_report_offline (Dwfl *dwfl, const char *release, 359cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*predicate) (const char *, 360cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *)); 361cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 362cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 363cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Call dwfl_report_module for each file mapped into the address space of PID. 364cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero on success, -1 if dwfl_report_module failed, 365cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or an errno code if opening the kernel binary failed. */ 366cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_proc_report (Dwfl *dwfl, pid_t pid); 367cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 368cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Similar, but reads an input stream in the format of Linux /proc/PID/maps 369cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng files giving module layout, not the file for a live process. */ 370cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_proc_maps_report (Dwfl *dwfl, FILE *); 371cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 372cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Trivial find_elf callback for use with dwfl_linux_proc_report. 373cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This uses the module name as a file name directly and tries to open it 374cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if it begin with a slash, or handles the magic string "[vdso]". */ 375cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_linux_proc_find_elf (Dwfl_Module *mod, void **userdata, 376cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *module_name, Dwarf_Addr base, 377cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng char **file_name, Elf **); 378cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 379cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Standard argument parsing for using a standard callback set. */ 380cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengstruct argp; 381cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const struct argp *dwfl_standard_argp (void) __attribute__ ((const)); 382cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 383cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 384cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/*** Relocation of addresses from Dwfl ***/ 385cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 386cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the number of relocatable bases associated with the module, 387cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng which is zero for ET_EXEC and one for ET_DYN. Returns -1 for errors. */ 388cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_relocations (Dwfl_Module *mod); 389cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 390cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the relocation base index associated with the *ADDRESS location, 391cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and adjust *ADDRESS to be an offset relative to that base. 392cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns -1 for errors. */ 393cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_relocate_address (Dwfl_Module *mod, 394cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *address); 395cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 396cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the ELF section name for the given relocation base index; 397cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng if SHNDXP is not null, set *SHNDXP to the ELF section index. 398cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng For ET_DYN, returns "" and sets *SHNDXP to SHN_ABS; the relocation 399cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng base is the runtime start address reported for the module. 400cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns null for errors. */ 401cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_module_relocation_info (Dwfl_Module *mod, 402cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng unsigned int idx, 403cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Word *shndxp); 404cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 405cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Validate that ADDRESS and ADDRESS+OFFSET lie in a known module 406cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and both within the same contiguous region for relocation purposes. 407cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero for success and -1 for errors. */ 408cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_validate_address (Dwfl *dwfl, 409cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr address, Dwarf_Sword offset); 410cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 411cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 412cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/*** ELF access functions ***/ 413cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 414cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Fetch the module main ELF file (where the allocated sections 415cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng are found) for use with libelf. If successful, fills in *BIAS 416cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng with the difference between addresses within the loaded module 417cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and those in symbol tables or Dwarf information referring to it. */ 418cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Elf *dwfl_module_getelf (Dwfl_Module *, GElf_Addr *bias); 419cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 420cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the number of symbols in the module's symbol table, 421cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng or -1 for errors. */ 422cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_getsymtab (Dwfl_Module *mod); 423cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 424cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Fetch one entry from the module's symbol table. On errors, returns 425cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng NULL. If successful, fills in *SYM and returns the string for st_name. 426cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng This works like gelf_getsym except that st_value is always adjusted 427cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng to an absolute value based on the module's location. If SHNDXP is 428cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng non-null, it's set with the section index (whether from st_shndx or 429cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng extended index table). */ 430cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_module_getsym (Dwfl_Module *mod, int ndx, 431cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Sym *sym, GElf_Word *shndxp) 432cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 433cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 434cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the symbol that ADDRESS lies inside, and return its name. */ 435cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_module_addrname (Dwfl_Module *mod, GElf_Addr address); 436cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 437cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the symbol that ADDRESS lies inside, and return detailed 438cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng information as for dwfl_module_getsym (above). */ 439cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_module_addrsym (Dwfl_Module *mod, GElf_Addr address, 440cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng GElf_Sym *sym, GElf_Word *shndxp) 441cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 442cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 443cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the ELF section that *ADDRESS lies inside and return it. 444cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng On success, adjusts *ADDRESS to be relative to the section, 445cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and sets *BIAS to the difference between addresses used in 446cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng the returned section's headers and run-time addresses. */ 447cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Elf_Scn *dwfl_module_address_section (Dwfl_Module *mod, 448cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *address, 449cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr *bias) 450cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (2, 3); 451cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 452cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 453cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/*** Dwarf access functions ***/ 454cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 455cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Fetch the module's debug information for use with libdw. 456cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng If successful, fills in *BIAS with the difference between 457cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng addresses within the loaded module and those to use with libdw. */ 458cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf *dwfl_module_getdwarf (Dwfl_Module *, Dwarf_Addr *bias) 459cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (2); 460cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 461cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Get the libdw handle for each module. */ 462cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern ptrdiff_t dwfl_getdwarf (Dwfl *, 463cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*callback) (Dwfl_Module *, void **, 464cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *, Dwarf_Addr, 465cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf *, Dwarf_Addr, void *), 466cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg, ptrdiff_t offset); 467cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 468cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Look up the module containing ADDR and return its debugging information, 469cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng loading it if necessary. */ 470cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf *dwfl_addrdwarf (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias) 471cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 472cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 473cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 474cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Find the CU containing ADDR and return its DIE. */ 475cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf_Die *dwfl_addrdie (Dwfl *dwfl, Dwarf_Addr addr, Dwarf_Addr *bias) 476cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 477cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf_Die *dwfl_module_addrdie (Dwfl_Module *mod, 478cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Addr addr, Dwarf_Addr *bias) 479cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 480cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 481cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Iterate through the CUs, start with null for LASTCU. */ 482cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf_Die *dwfl_nextcu (Dwfl *dwfl, Dwarf_Die *lastcu, Dwarf_Addr *bias) 483cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 484cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf_Die *dwfl_module_nextcu (Dwfl_Module *mod, 485cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Die *lastcu, Dwarf_Addr *bias) 486cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng __nonnull_attribute__ (3); 487cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 488cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the module containing the CU DIE. */ 489cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_cumodule (Dwarf_Die *cudie); 490cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 491cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 492cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Cache the source line information fo the CU and return the 493cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng number of Dwfl_Line entries it has. */ 494cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_getsrclines (Dwarf_Die *cudie, size_t *nlines); 495cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 496cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Access one line number entry within the CU. */ 497cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Line *dwfl_onesrcline (Dwarf_Die *cudie, size_t idx); 498cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 499cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Get source for address. */ 500cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Line *dwfl_module_getsrc (Dwfl_Module *mod, Dwarf_Addr addr); 501cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Line *dwfl_getsrc (Dwfl *dwfl, Dwarf_Addr addr); 502cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 503cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Get address for source. */ 504cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_getsrc_file (Dwfl_Module *mod, 505cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *fname, int lineno, int column, 506cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwfl_Line ***srcsp, size_t *nsrcs); 507cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 508cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the module containing this line record. */ 509cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwfl_Module *dwfl_linemodule (Dwfl_Line *line); 510cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 511cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the CU containing this line record. */ 512cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern Dwarf_Die *dwfl_linecu (Dwfl_Line *line); 513cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 514cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the source file name and fill in other information. 515cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Arguments may be null for unneeded fields. */ 516cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_lineinfo (Dwfl_Line *line, Dwarf_Addr *addr, 517cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int *linep, int *colp, 518cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Word *mtime, Dwarf_Word *length); 519cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 520cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return the compilation directory (AT_comp_dir) from this line's CU. */ 521cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern const char *dwfl_line_comp_dir (Dwfl_Line *line); 522cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 523cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 524cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/*** Machine backend access functions ***/ 525cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 526cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Return location expression to find return value given a 527cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing 528cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng function itself (whose DW_AT_type attribute describes its return type). 529cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng The given DIE must come from the given module. Returns -1 for errors. 530cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Returns zero if the function has no return value (e.g. "void" in C). 531cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Otherwise, *LOCOPS gets a location expression to find the return value, 532cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng and returns the number of operations in the expression. The pointer is 533cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng permanently allocated at least as long as the module is live. */ 534cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_return_value_location (Dwfl_Module *mod, 535cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng Dwarf_Die *functypedie, 536cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const Dwarf_Op **locops); 537cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 538cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng/* Enumerate the DWARF register numbers and their names. 539cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng For each register, CALLBACK gets its DWARF number, a string describing 540cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng the register set (such as "integer" or "FPU"), a prefix used in 541cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng assembler syntax (such as "%" or "$", may be ""), and the name for the 542cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng register (contains identifier characters only, possibly all digits). 543cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng The REGNAME string is valid only during the callback. */ 544cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Chengextern int dwfl_module_register_names (Dwfl_Module *mod, 545cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int (*callback) (void *arg, 546cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int regno, 547cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *setname, 548cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *prefix, 549cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng const char *regname, 550cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng int bits, int type), 551cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng void *arg); 552cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 553cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 554cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#ifdef __cplusplus 555cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng} 556cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#endif 557cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng 558cc6695e2684ce93cdf8bd2da63d55d2cf49ff076Ben Cheng#endif /* libdwfl.h */ 559