1/* Copyright (C) 2007-2010 The Android Open Source Project
2**
3** This software is licensed under the terms of the GNU General Public
4** License version 2, as published by the Free Software Foundation, and
5** may be copied, distributed, and modified under those terms.
6**
7** This program is distributed in the hope that it will be useful,
8** but WITHOUT ANY WARRANTY; without even the implied warranty of
9** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10** GNU General Public License for more details.
11*/
12
13/*
14 * Contains declaration of types, strctures, routines, etc. that encapsulte
15 * an API for parsing an ELF file containing debugging information in DWARF
16 * format.
17 */
18
19#ifndef ELFF_API_H_
20#define ELFF_API_H_
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26#include <stdint.h>
27
28/* Defines type for a handle used in ELFF API. */
29typedef void* ELFF_HANDLE;
30
31/* Defines an entry for 'inline_stack' array in Elf_AddressInfo structure.
32 * Each entry in the array represents a routine, where routine represented
33 * with the previous array entry has been inlined. First element in the array
34 * (at index 0) represents information for the inlined routine, referenced by
35 * Elf_AddressInfo structure itself. If name for a routine was not available
36 * (DW_AT_name attribute was missing), routine name is set to "<unknown>".
37 * Last entry in the array has all its fields set to zero. It's sufficient
38 * just to check for routine_name field of this structure to be NULL to detect
39 * last entry in the array.
40 */
41typedef struct Elf_InlineInfo {
42  /* Name of the routine where previous routine is inlined.
43   * This field can never be NULL, except for the last array entry.
44   */
45  const char*     routine_name;
46
47  /* Source file name where routine is inlined.
48   * This field can be NULL, if it was not possible to obtain information
49   * about source file location for the routine. If this field is NULL, content
50   * of inlined_in_file_dir and inlined_at_line fields is undefined and should
51   * be ignored. */
52  const char*     inlined_in_file;
53
54  /* Source file directory where routine is inlined.
55   * If inlined_in_file field contains NULL, content of this field is undefined
56   * and should be ignored. */
57  const char*     inlined_in_file_dir;
58
59  /* Source file line number where routine is inlined.
60   * If inlined_in_file field contains NULL, content of this field is undefined
61   * and should be ignored. */
62  uint32_t        inlined_at_line;
63} Elf_InlineInfo;
64
65/* Checks if an entry is the last entry in the array.
66 * Return:
67 *  Boolean: 1 if this is last entry, or zero otherwise.
68 */
69static inline int
70elfinlineinfo_is_last_entry(const Elf_InlineInfo* info) {
71    return info->routine_name == 0;
72}
73
74/* PC address information descriptor.
75 * This descriptor contains as much information about a PC address as it was
76 * possible to collect from an ELF file. */
77typedef struct Elf_AddressInfo {
78  /* Name of the routine containing the address. If name of the routine
79   * was not available (DW_AT_name attribute was missing) this field
80   * is set to "<unknown>". */
81  const char*       routine_name;
82
83  /* Name of the source file containing the routine. If source location for the
84   * routine was not available, this field is set to NULL, and content of
85   * dir_name, and line_number fields of this structure is not defined. */
86  const char*       file_name;
87
88  /* Path to the source file directory. If file_name field of this structure is
89   * NULL, content of this field is not defined. */
90  const char*       dir_name;
91
92  /* Line number in the source file for the address. If file_name field of this
93   * structure is NULL, content of this field is not defined. */
94  uint32_t          line_number;
95
96  /* If routine that contains the given address has been inlined (or it is part
97   * of even deeper inline branch) this array lists information about that
98   * inline branch rooting to the first routine that has not been inlined. The
99   * first element in the array references a routine, where routine containing
100   * the given address has been inlined. The second entry contains information
101   * about a routine referenced by the first entry (and so on). If routine,
102   * containing the given address has not been inlined, this field is set to
103   * NULL. The array ends with an entry containing all zeroes. */
104  Elf_InlineInfo*   inline_stack;
105} Elf_AddressInfo;
106
107//=============================================================================
108// API routines
109//=============================================================================
110
111/* Initializes ELFF API for the given ELF file.
112 * Param:
113 *  elf_file_path - Path to the ELF file to initialize API for.
114 * Return:
115 *  On success, this routine returns a handle that can be used in subsequent
116 *  calls to this API dealing with the given ELF file. On failure this routine
117 *  returns NULL, with errno providing extended error information.
118 *  NOTE: handle returned from this routine must be closed using elff_close().
119 */
120ELFF_HANDLE elff_init(const char* elf_file_path);
121
122/* Closes a handle obtained after successful call to elff_init routine.
123 * Param:
124 *  handle - A handle to close. This handle must be a handle returned from
125 *  a successful call to elff_init routine.
126 */
127void elff_close(ELFF_HANDLE handle);
128
129/* Checks if ELF file represents an executable file, or a shared library.
130 *  handle - A handle obtained from successful call to elff_init().
131 * Return:
132 *  1  if ELF file represents an executable file, or
133 *  0  if ELF file represents a shared library, or
134 *  -1 if handle is invalid.
135 */
136int elff_is_exec(ELFF_HANDLE handle);
137
138/* Gets PC address information.
139 * Param:
140 *  handle - A handle obtained from successful call to elff_init().
141 *  address - PC address to get information for. Address must be relative to
142 *    the beginning of ELF file represented by the handle parameter.
143 *  address_info - Upon success contains information about routine(s) that
144 *    contain the given address.
145 * Return:
146 *  0 if routine(s) containing the given address has been found and information
147 *  has been saved into address_info, or -1 if no appropriate routine for that
148 *  address has been found, or there was a memory error when collecting
149 *  routine(s) information. In case of failure, errno provides extended
150 *  error information.
151 *  NOTE: Successful call to this routine must be complimented with a call
152 *  to free_pc_address_info, so ELFF API can release resources aquired for
153 *  address_info.
154 */
155int elff_get_pc_address_info(ELFF_HANDLE handle,
156                             uint64_t address,
157                             Elf_AddressInfo* address_info);
158
159/* Frees resources acquired for address information in successful call to
160 * get_pc_address_info().
161 * Param:
162 *  handle - A handle obtained from successful call to elff_init().
163 *  address_info - Address information structure, initialized in successful
164 *    call to get_pc_address_info() routine.
165 */
166void elff_free_pc_address_info(ELFF_HANDLE handle,
167                               Elf_AddressInfo* address_info);
168
169#ifdef __cplusplus
170}   /* end of extern "C" */
171#endif
172
173#endif  // ELFF_API_H_
174