diff options
Diffstat (limited to 'elff/elff_api.h')
| -rw-r--r-- | elff/elff_api.h | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/elff/elff_api.h b/elff/elff_api.h new file mode 100644 index 0000000..7b02746 --- /dev/null +++ b/elff/elff_api.h @@ -0,0 +1,173 @@ +/* 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 "qemu-common.h"
+
+/* 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 "<unknown>".
+ * 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 "<unknown>". */
+ 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_
|