1 /* Interface for libebl. 2 Copyright (C) 2000, 2001, 2002, 2004, 2005, 2006, 2007, 2008 Red Hat, Inc. 3 This file is part of Red Hat elfutils. 4 5 Red Hat elfutils is free software; you can redistribute it and/or modify 6 it under the terms of the GNU General Public License as published by the 7 Free Software Foundation; version 2 of the License. 8 9 Red Hat elfutils is distributed in the hope that it will be useful, but 10 WITHOUT ANY WARRANTY; without even the implied warranty of 11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 General Public License for more details. 13 14 You should have received a copy of the GNU General Public License along 15 with Red Hat elfutils; if not, write to the Free Software Foundation, 16 Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA. 17 18 In addition, as a special exception, Red Hat, Inc. gives You the 19 additional right to link the code of Red Hat elfutils with code licensed 20 under any Open Source Initiative certified open source license 21 (http://www.opensource.org/licenses/index.php) which requires the 22 distribution of source code with any binary distribution and to 23 distribute linked combinations of the two. Non-GPL Code permitted under 24 this exception must only link to the code of Red Hat elfutils through 25 those well defined interfaces identified in the file named EXCEPTION 26 found in the source code files (the "Approved Interfaces"). The files 27 of Non-GPL Code may instantiate templates or use macros or inline 28 functions from the Approved Interfaces without causing the resulting 29 work to be covered by the GNU General Public License. Only Red Hat, 30 Inc. may make changes or additions to the list of Approved Interfaces. 31 Red Hat's grant of this exception is conditioned upon your not adding 32 any new exceptions. If you wish to add a new Approved Interface or 33 exception, please contact Red Hat. You must obey the GNU General Public 34 License in all respects for all of the Red Hat elfutils code and other 35 code used in conjunction with Red Hat elfutils except the Non-GPL Code 36 covered by this exception. If you modify this file, you may extend this 37 exception to your version of the file, but you are not obligated to do 38 so. If you do not wish to provide this exception without modification, 39 you must delete this exception statement from your version and license 40 this file solely under the GPL without exception. 41 42 Red Hat elfutils is an included package of the Open Invention Network. 43 An included package of the Open Invention Network is a package for which 44 Open Invention Network licensees cross-license their patents. No patent 45 license is granted, either expressly or impliedly, by designation as an 46 included package. Should you wish to participate in the Open Invention 47 Network licensing program, please visit www.openinventionnetwork.com 48 <http://www.openinventionnetwork.com>. */ 49 50 #ifndef _LIBEBL_H 51 #define _LIBEBL_H 1 52 53 #include <gelf.h> 54 #include "libdw.h" 55 #include <stdbool.h> 56 #include <stddef.h> 57 #include <stdint.h> 58 59 #include "elf-knowledge.h" 60 61 62 /* Opaque type for the handle. */ 63 typedef struct ebl Ebl; 64 65 66 #ifdef __cplusplus 67 extern "C" { 68 #endif 69 70 /* Get backend handle for object associated with ELF handle. */ 71 extern Ebl *ebl_openbackend (Elf *elf); 72 /* Similar but without underlying ELF file. */ 73 extern Ebl *ebl_openbackend_machine (GElf_Half machine); 74 /* Similar but with emulation name given. */ 75 extern Ebl *ebl_openbackend_emulation (const char *emulation); 76 77 /* Free resources allocated for backend handle. */ 78 extern void ebl_closebackend (Ebl *bh); 79 80 81 /* Information about the descriptor. */ 82 83 /* Get ELF machine. */ 84 extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__)); 85 86 /* Get ELF class. */ 87 extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__)); 88 89 /* Get ELF data encoding. */ 90 extern int ebl_get_elfdata (Ebl *ebl) __attribute__ ((__pure__)); 91 92 93 /* Function to call the callback functions including default ELF 94 handling. */ 95 96 /* Return backend name. */ 97 extern const char *ebl_backend_name (Ebl *ebl); 98 99 /* Return relocation type name. */ 100 extern const char *ebl_object_type_name (Ebl *ebl, int object, 101 char *buf, size_t len); 102 103 /* Return relocation type name. */ 104 extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc, 105 char *buf, size_t len); 106 107 /* Check relocation type. */ 108 extern bool ebl_reloc_type_check (Ebl *ebl, int reloc); 109 110 /* Check relocation type use. */ 111 extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc); 112 113 /* Check if relocation type is for simple absolute relocations. 114 Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM. */ 115 extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc); 116 117 /* Return true if the symbol type is that referencing the GOT. E.g., 118 R_386_GOTPC. */ 119 extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc); 120 121 /* Return segment type name. */ 122 extern const char *ebl_segment_type_name (Ebl *ebl, int segment, 123 char *buf, size_t len); 124 125 /* Return section type name. */ 126 extern const char *ebl_section_type_name (Ebl *ebl, int section, 127 char *buf, size_t len); 128 129 /* Return section name. */ 130 extern const char *ebl_section_name (Ebl *ebl, int section, int xsection, 131 char *buf, size_t len, 132 const char *scnnames[], size_t shnum); 133 134 /* Return machine flag names. */ 135 extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags, 136 char *buf, size_t len); 137 138 /* Check whether machine flag is valid. */ 139 extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags); 140 141 /* Check whether SHF_MASKPROC flags are valid. */ 142 extern bool ebl_machine_section_flag_check (Ebl *ebl, GElf_Xword flags); 143 144 /* Check whether the section with the given index, header, and name 145 is a special machine section that is valid despite a combination 146 of flags or other details that are not generically valid. */ 147 extern bool ebl_check_special_section (Ebl *ebl, int ndx, 148 const GElf_Shdr *shdr, const char *name); 149 150 /* Return symbol type name. */ 151 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol, 152 char *buf, size_t len); 153 154 /* Return symbol binding name. */ 155 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding, 156 char *buf, size_t len); 157 158 /* Return dynamic tag name. */ 159 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag, 160 char *buf, size_t len); 161 162 /* Check dynamic tag. */ 163 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag); 164 165 /* Check whether given symbol's st_value and st_size are OK despite failing 166 normal checks. */ 167 extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr, 168 const GElf_Sym *sym, const char *name, 169 const GElf_Shdr *destshdr); 170 171 /* Return combined section header flags value. */ 172 extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1, 173 GElf_Word flags2); 174 175 /* Return symbolic representation of OS ABI. */ 176 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len); 177 178 179 /* Return name of the note section type for a core file. */ 180 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf, 181 size_t len); 182 183 /* Return name of the note section type for an object file. */ 184 extern const char *ebl_object_note_type_name (Ebl *ebl, uint32_t type, 185 char *buf, size_t len); 186 187 /* Print information about object note if available. */ 188 extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type, 189 uint32_t descsz, const char *desc); 190 191 /* Check whether an attribute in a .gnu_attributes section is recognized. 192 Fills in *TAG_NAME with the name for this tag. 193 If VALUE is a known value for that tag, also fills in *VALUE_NAME. */ 194 extern bool ebl_check_object_attribute (Ebl *ebl, const char *vendor, 195 int tag, uint64_t value, 196 const char **tag_name, 197 const char **value_name); 198 199 200 /* Check section name for being that of a debug informatino section. */ 201 extern bool ebl_debugscn_p (Ebl *ebl, const char *name); 202 203 /* Check whether given relocation is a copy relocation. */ 204 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc); 205 206 /* Check whether given relocation is a no-op relocation. */ 207 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc); 208 209 /* Check whether given relocation is a relative relocation. */ 210 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc); 211 212 /* Check whether section should be stripped. */ 213 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr, 214 const GElf_Shdr *shdr, const char *name, 215 bool remove_comment, bool only_remove_debug); 216 217 /* Check if backend uses a bss PLT in this file. */ 218 extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr); 219 220 /* Return size of entry in SysV-style hash table. */ 221 extern int ebl_sysvhash_entrysize (Ebl *ebl); 222 223 /* Return location expression to find return value given a 224 DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing 225 function itself (whose DW_AT_type attribute describes its return type). 226 Returns -1 for a libdw error (see dwarf_errno). 227 Returns -2 for an unrecognized type formation. 228 Returns zero if the function has no return value (e.g. "void" in C). 229 Otherwise, *LOCOPS gets a location expression to find the return value, 230 and returns the number of operations in the expression. The pointer is 231 permanently allocated at least as long as the Ebl handle is open. */ 232 extern int ebl_return_value_location (Ebl *ebl, 233 Dwarf_Die *functypedie, 234 const Dwarf_Op **locops); 235 236 /* Fill in register information given DWARF register numbers. 237 If NAME is null, return the maximum REGNO + 1 that has a name. 238 Otherwise, store in NAME the name for DWARF register number REGNO 239 and return the number of bytes written (including '\0' terminator). 240 Return -1 if NAMELEN is too short or REGNO is negative or too large. 241 Return 0 if REGNO is unused (a gap in the DWARF number assignment). 242 On success, set *SETNAME to a description like "integer" or "FPU" 243 fit for "%s registers" title display, and *PREFIX to the string 244 that precedes NAME in canonical assembler syntax (e.g. "%" or "$"). 245 The NAME string contains identifier characters only (maybe just digits). */ 246 extern ssize_t ebl_register_info (Ebl *ebl, 247 int regno, char *name, size_t namelen, 248 const char **prefix, const char **setname, 249 int *bits, int *type); 250 251 /* Fill in the DWARF register numbers for the registers used in system calls. 252 The SP and PC are what kernel reports call the user stack pointer and PC. 253 The CALLNO and ARGS are the system call number and incoming arguments. 254 Each of these is filled with the DWARF register number corresponding, 255 or -1 if there is none. Returns zero when the information is available. */ 256 extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc, 257 int *callno, int args[6]); 258 259 /* ELF string table handling. */ 260 struct Ebl_Strtab; 261 struct Ebl_Strent; 262 263 /* Create new ELF string table object in memory. */ 264 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr); 265 266 /* Free resources allocated for ELF string table ST. */ 267 extern void ebl_strtabfree (struct Ebl_Strtab *st); 268 269 /* Add string STR (length LEN is != 0) to ELF string table ST. */ 270 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st, 271 const char *str, size_t len); 272 273 /* Finalize string table ST and store size and memory location information 274 in DATA. */ 275 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data); 276 277 /* Get offset in string table for string associated with SE. */ 278 extern size_t ebl_strtaboffset (struct Ebl_Strent *se); 279 280 /* Return the string associated with SE. */ 281 extern const char *ebl_string (struct Ebl_Strent *se); 282 283 284 /* ELF wide char string table handling. */ 285 struct Ebl_WStrtab; 286 struct Ebl_WStrent; 287 288 /* Create new ELF wide char string table object in memory. */ 289 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr); 290 291 /* Free resources allocated for ELF wide char string table ST. */ 292 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st); 293 294 /* Add string STR (length LEN is != 0) to ELF string table ST. */ 295 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st, 296 const wchar_t *str, size_t len); 297 298 /* Finalize string table ST and store size and memory location information 299 in DATA. */ 300 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data); 301 302 /* Get offset in wide char string table for string associated with SE. */ 303 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se); 304 305 306 /* Generic string table handling. */ 307 struct Ebl_GStrtab; 308 struct Ebl_GStrent; 309 310 /* Create new string table object in memory. */ 311 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr); 312 313 /* Free resources allocated for string table ST. */ 314 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st); 315 316 /* Add string STR (length LEN is != 0) to string table ST. */ 317 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st, 318 const char *str, size_t len); 319 320 /* Finalize string table ST and store size and memory location information 321 in DATA. */ 322 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data); 323 324 /* Get offset in wide char string table for string associated with SE. */ 325 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se); 326 327 328 /* Register map info. */ 329 typedef struct 330 { 331 Dwarf_Half offset; /* Byte offset in register data block. */ 332 Dwarf_Half regno; /* DWARF register number. */ 333 uint8_t bits; /* Bits of data for one register. */ 334 uint8_t pad; /* Bytes of padding after register's data. */ 335 Dwarf_Half count; /* Consecutive register numbers here. */ 336 } Ebl_Register_Location; 337 338 /* Non-register data items in core notes. */ 339 typedef struct 340 { 341 const char *name; /* Printable identifier. */ 342 const char *group; /* Identifier for category of related items. */ 343 Dwarf_Half offset; /* Byte offset in note data. */ 344 Dwarf_Half count; 345 Elf_Type type; 346 char format; 347 bool thread_identifier; 348 } Ebl_Core_Item; 349 350 /* Describe the format of a core file note with type field matching N_TYPE 351 and descriptor size matching DESCSZ. */ 352 extern int ebl_core_note (Ebl *ebl, GElf_Word n_type, GElf_Word descsz, 353 GElf_Word *regs_offset, size_t *nregloc, 354 const Ebl_Register_Location **reglocs, 355 size_t *nitems, const Ebl_Core_Item **items) 356 __nonnull_attribute__ (1, 4, 5, 6, 7, 8); 357 358 /* Describe the auxv type number. */ 359 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type, 360 const char **name, const char **format) 361 __nonnull_attribute__ (1, 3, 4); 362 363 364 #ifdef __cplusplus 365 } 366 #endif 367 368 #endif /* libebl.h */ 369
