/* Copyright (C) 2007-2010 The Android Open Source Project ** ** This software is licensed under the terms of the GNU General Public ** License version 2, as published by the Free Software Foundation, and ** may be copied, distributed, and modified under those terms. ** ** This program is distributed in the hope that it will be useful, ** but WITHOUT ANY WARRANTY; without even the implied warranty of ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ** GNU General Public License for more details. */ /* * Contains declaration of types, strctures, routines, etc. that encapsulte * an API for parsing an ELF file containing debugging information in DWARF * format. */ #ifndef ELFF_API_H_ #define ELFF_API_H_ #ifdef __cplusplus extern "C" { #endif #include /* Defines type for a handle used in ELFF API. */ typedef void* ELFF_HANDLE; /* Defines an entry for 'inline_stack' array in Elf_AddressInfo structure. * Each entry in the array represents a routine, where routine represented * with the previous array entry has been inlined. First element in the array * (at index 0) represents information for the inlined routine, referenced by * Elf_AddressInfo structure itself. If name for a routine was not available * (DW_AT_name attribute was missing), routine name is set to "". * Last entry in the array has all its fields set to zero. It's sufficient * just to check for routine_name field of this structure to be NULL to detect * last entry in the array. */ typedef struct Elf_InlineInfo { /* Name of the routine where previous routine is inlined. * This field can never be NULL, except for the last array entry. */ const char* routine_name; /* Source file name where routine is inlined. * This field can be NULL, if it was not possible to obtain information * about source file location for the routine. If this field is NULL, content * of inlined_in_file_dir and inlined_at_line fields is undefined and should * be ignored. */ const char* inlined_in_file; /* Source file directory where routine is inlined. * If inlined_in_file field contains NULL, content of this field is undefined * and should be ignored. */ const char* inlined_in_file_dir; /* Source file line number where routine is inlined. * If inlined_in_file field contains NULL, content of this field is undefined * and should be ignored. */ uint32_t inlined_at_line; } Elf_InlineInfo; /* Checks if an entry is the last entry in the array. * Return: * Boolean: 1 if this is last entry, or zero otherwise. */ static inline int elfinlineinfo_is_last_entry(const Elf_InlineInfo* info) { return info->routine_name == 0; } /* PC address information descriptor. * This descriptor contains as much information about a PC address as it was * possible to collect from an ELF file. */ typedef struct Elf_AddressInfo { /* Name of the routine containing the address. If name of the routine * was not available (DW_AT_name attribute was missing) this field * is set to "". */ const char* routine_name; /* Name of the source file containing the routine. If source location for the * routine was not available, this field is set to NULL, and content of * dir_name, and line_number fields of this structure is not defined. */ const char* file_name; /* Path to the source file directory. If file_name field of this structure is * NULL, content of this field is not defined. */ const char* dir_name; /* Line number in the source file for the address. If file_name field of this * structure is NULL, content of this field is not defined. */ uint32_t line_number; /* If routine that contains the given address has been inlined (or it is part * of even deeper inline branch) this array lists information about that * inline branch rooting to the first routine that has not been inlined. The * first element in the array references a routine, where routine containing * the given address has been inlined. The second entry contains information * about a routine referenced by the first entry (and so on). If routine, * containing the given address has not been inlined, this field is set to * NULL. The array ends with an entry containing all zeroes. */ Elf_InlineInfo* inline_stack; } Elf_AddressInfo; //============================================================================= // API routines //============================================================================= /* Initializes ELFF API for the given ELF file. * Param: * elf_file_path - Path to the ELF file to initialize API for. * Return: * On success, this routine returns a handle that can be used in subsequent * calls to this API dealing with the given ELF file. On failure this routine * returns NULL, with errno providing extended error information. * NOTE: handle returned from this routine must be closed using elff_close(). */ ELFF_HANDLE elff_init(const char* elf_file_path); /* Closes a handle obtained after successful call to elff_init routine. * Param: * handle - A handle to close. This handle must be a handle returned from * a successful call to elff_init routine. */ void elff_close(ELFF_HANDLE handle); /* Checks if ELF file represents an executable file, or a shared library. * handle - A handle obtained from successful call to elff_init(). * Return: * 1 if ELF file represents an executable file, or * 0 if ELF file represents a shared library, or * -1 if handle is invalid. */ int elff_is_exec(ELFF_HANDLE handle); /* Gets PC address information. * Param: * handle - A handle obtained from successful call to elff_init(). * address - PC address to get information for. Address must be relative to * the beginning of ELF file represented by the handle parameter. * address_info - Upon success contains information about routine(s) that * contain the given address. * Return: * 0 if routine(s) containing the given address has been found and information * has been saved into address_info, or -1 if no appropriate routine for that * address has been found, or there was a memory error when collecting * routine(s) information. In case of failure, errno provides extended * error information. * NOTE: Successful call to this routine must be complimented with a call * to free_pc_address_info, so ELFF API can release resources aquired for * address_info. */ int elff_get_pc_address_info(ELFF_HANDLE handle, uint64_t address, Elf_AddressInfo* address_info); /* Frees resources acquired for address information in successful call to * get_pc_address_info(). * Param: * handle - A handle obtained from successful call to elff_init(). * address_info - Address information structure, initialized in successful * call to get_pc_address_info() routine. */ void elff_free_pc_address_info(ELFF_HANDLE handle, Elf_AddressInfo* address_info); #ifdef __cplusplus } /* end of extern "C" */ #endif #endif // ELFF_API_H_