1 /* Interface for libebl. 2 Copyright (C) 2000-2010, 2013, 2014 Red Hat, Inc. 3 This file is part of elfutils. 4 5 This file is free software; you can redistribute it and/or modify 6 it under the terms of either 7 8 * the GNU Lesser General Public License as published by the Free 9 Software Foundation; either version 3 of the License, or (at 10 your option) any later version 11 12 or 13 14 * the GNU General Public License as published by the Free 15 Software Foundation; either version 2 of the License, or (at 16 your option) any later version 17 18 or both in parallel, as here. 19 20 elfutils is distributed in the hope that it will be useful, but 21 WITHOUT ANY WARRANTY; without even the implied warranty of 22 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 23 General Public License for more details. 24 25 You should have received copies of the GNU General Public License and 26 the GNU Lesser General Public License along with this program. If 27 not, see <http://www.gnu.org/licenses/>. */ 28 29 #ifndef _LIBEBL_H 30 #define _LIBEBL_H 1 31 32 #include <gelf.h> 33 #include "libdw.h" 34 #include <stdbool.h> 35 #include <stddef.h> 36 #include <stdint.h> 37 38 #include "elf-knowledge.h" 39 40 41 /* Opaque type for the handle. */ 42 typedef struct ebl Ebl; 43 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /* Get backend handle for object associated with ELF handle. */ 50 extern Ebl *ebl_openbackend (Elf *elf); 51 /* Similar but without underlying ELF file. */ 52 extern Ebl *ebl_openbackend_machine (GElf_Half machine); 53 /* Similar but with emulation name given. */ 54 extern Ebl *ebl_openbackend_emulation (const char *emulation); 55 56 /* Free resources allocated for backend handle. */ 57 extern void ebl_closebackend (Ebl *bh); 58 59 60 /* Information about the descriptor. */ 61 62 /* Get ELF machine. */ 63 extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__)); 64 65 /* Get ELF class. */ 66 extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__)); 67 68 /* Get ELF data encoding. */ 69 extern int ebl_get_elfdata (Ebl *ebl) __attribute__ ((__pure__)); 70 71 72 /* Function to call the callback functions including default ELF 73 handling. */ 74 75 /* Return backend name. */ 76 extern const char *ebl_backend_name (Ebl *ebl); 77 78 /* Return relocation type name. */ 79 extern const char *ebl_object_type_name (Ebl *ebl, int object, 80 char *buf, size_t len); 81 82 /* Return relocation type name. */ 83 extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc, 84 char *buf, size_t len); 85 86 /* Check relocation type. */ 87 extern bool ebl_reloc_type_check (Ebl *ebl, int reloc); 88 89 /* Check relocation type use. */ 90 extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc); 91 92 /* Check if relocation type is for simple absolute relocations. 93 Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM. */ 94 extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc); 95 96 /* Return true if the symbol type is that referencing the GOT. E.g., 97 R_386_GOTPC. */ 98 extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc); 99 100 /* Return segment type name. */ 101 extern const char *ebl_segment_type_name (Ebl *ebl, int segment, 102 char *buf, size_t len); 103 104 /* Return section type name. */ 105 extern const char *ebl_section_type_name (Ebl *ebl, int section, 106 char *buf, size_t len); 107 108 /* Return section name. */ 109 extern const char *ebl_section_name (Ebl *ebl, int section, int xsection, 110 char *buf, size_t len, 111 const char *scnnames[], size_t shnum); 112 113 /* Return machine flag names. */ 114 extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags, 115 char *buf, size_t len); 116 117 /* Check whether machine flag is valid. */ 118 extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags); 119 120 /* Check whether SHF_MASKPROC flags are valid. */ 121 extern bool ebl_machine_section_flag_check (Ebl *ebl, GElf_Xword flags); 122 123 /* Check whether the section with the given index, header, and name 124 is a special machine section that is valid despite a combination 125 of flags or other details that are not generically valid. */ 126 extern bool ebl_check_special_section (Ebl *ebl, int ndx, 127 const GElf_Shdr *shdr, const char *name); 128 129 /* Return symbol type name. */ 130 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol, 131 char *buf, size_t len); 132 133 /* Return symbol binding name. */ 134 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding, 135 char *buf, size_t len); 136 137 /* Return dynamic tag name. */ 138 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag, 139 char *buf, size_t len); 140 141 /* Check dynamic tag. */ 142 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag); 143 144 /* Check whether given symbol's st_value and st_size are OK despite failing 145 normal checks. */ 146 extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr, 147 const GElf_Sym *sym, const char *name, 148 const GElf_Shdr *destshdr); 149 150 /* Check whether only valid bits are set on the st_other symbol flag. */ 151 extern bool ebl_check_st_other_bits (Ebl *ebl, unsigned char st_other); 152 153 /* Return combined section header flags value. */ 154 extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1, 155 GElf_Word flags2); 156 157 /* Return symbolic representation of OS ABI. */ 158 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len); 159 160 161 /* Return name of the note section type for a core file. */ 162 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf, 163 size_t len); 164 165 /* Return name of the note section type for an object file. */ 166 extern const char *ebl_object_note_type_name (Ebl *ebl, const char *name, 167 uint32_t type, char *buf, 168 size_t len); 169 170 /* Print information about object note if available. */ 171 extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type, 172 uint32_t descsz, const char *desc); 173 174 /* Check whether an attribute in a .gnu_attributes section is recognized. 175 Fills in *TAG_NAME with the name for this tag. 176 If VALUE is a known value for that tag, also fills in *VALUE_NAME. */ 177 extern bool ebl_check_object_attribute (Ebl *ebl, const char *vendor, 178 int tag, uint64_t value, 179 const char **tag_name, 180 const char **value_name); 181 182 /* Check whether a section type is a valid reloc target. */ 183 extern bool ebl_check_reloc_target_type (Ebl *ebl, Elf64_Word sh_type); 184 185 186 /* Check section name for being that of a debug informatino section. */ 187 extern bool ebl_debugscn_p (Ebl *ebl, const char *name); 188 189 /* Check whether given relocation is a copy relocation. */ 190 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc); 191 192 /* Check whether given relocation is a no-op relocation. */ 193 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc); 194 195 /* Check whether given relocation is a relative relocation. */ 196 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc); 197 198 /* Check whether section should be stripped. */ 199 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr, 200 const GElf_Shdr *shdr, const char *name, 201 bool remove_comment, bool only_remove_debug); 202 203 /* Check if backend uses a bss PLT in this file. */ 204 extern bool ebl_bss_plt_p (Ebl *ebl); 205 206 /* Return size of entry in SysV-style hash table. */ 207 extern int ebl_sysvhash_entrysize (Ebl *ebl); 208 209 /* Return location expression to find return value given a 210 DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing 211 function itself (whose DW_AT_type attribute describes its return type). 212 Returns -1 for a libdw error (see dwarf_errno). 213 Returns -2 for an unrecognized type formation. 214 Returns zero if the function has no return value (e.g. "void" in C). 215 Otherwise, *LOCOPS gets a location expression to find the return value, 216 and returns the number of operations in the expression. The pointer is 217 permanently allocated at least as long as the Ebl handle is open. */ 218 extern int ebl_return_value_location (Ebl *ebl, 219 Dwarf_Die *functypedie, 220 const Dwarf_Op **locops); 221 222 /* Fill in register information given DWARF register numbers. 223 If NAME is null, return the maximum REGNO + 1 that has a name. 224 Otherwise, store in NAME the name for DWARF register number REGNO 225 and return the number of bytes written (including '\0' terminator). 226 Return -1 if NAMELEN is too short or REGNO is negative or too large. 227 Return 0 if REGNO is unused (a gap in the DWARF number assignment). 228 On success, set *SETNAME to a description like "integer" or "FPU" 229 fit for "%s registers" title display, and *PREFIX to the string 230 that precedes NAME in canonical assembler syntax (e.g. "%" or "$"). 231 The NAME string contains identifier characters only (maybe just digits). */ 232 extern ssize_t ebl_register_info (Ebl *ebl, 233 int regno, char *name, size_t namelen, 234 const char **prefix, const char **setname, 235 int *bits, int *type); 236 237 /* Fill in the DWARF register numbers for the registers used in system calls. 238 The SP and PC are what kernel reports call the user stack pointer and PC. 239 The CALLNO and ARGS are the system call number and incoming arguments. 240 Each of these is filled with the DWARF register number corresponding, 241 or -1 if there is none. Returns zero when the information is available. */ 242 extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc, 243 int *callno, int args[6]); 244 245 /* Supply the ABI-specified state of DWARF CFI before CIE initial programs. 246 247 The DWARF 3.0 spec says that the default initial states of all registers 248 are "undefined", unless otherwise specified by the machine/compiler ABI. 249 250 This default is wrong for every machine with the CFI generated by GCC. 251 The EH unwinder does not really distinguish "same_value" and "undefined", 252 since it doesn't matter for unwinding (in either case there is no change 253 to make for that register). GCC generates CFI that says nothing at all 254 about registers it hasn't spilled somewhere. For our unwinder to give 255 the true story, the backend must supply an initial state that uses 256 "same_value" rules for all the callee-saves registers. 257 258 This can fill in the initial_instructions, initial_instructions_end 259 members of *ABI_INFO to point at a CFI instruction stream to process 260 before each CIE's initial instructions. It should set the 261 data_alignment_factor member if it affects the initial instructions. 262 263 The callback should not use the register rules DW_CFA_expression or 264 DW_CFA_val_expression. Defining the CFA using DW_CFA_def_cfa_expression 265 is allowed. This is an implementation detail since register rules 266 store expressions as offsets from the .eh_frame or .debug_frame data. 267 268 As a shorthand for some common cases, for this instruction stream 269 we overload some CFI instructions that cannot be used in a CIE: 270 271 DW_CFA_restore -- Change default rule for all unmentioned 272 registers from undefined to same_value. 273 274 This function can also fill in ABI_INFO->return_address_register with the 275 DWARF register number that identifies the actual PC in machine state. 276 If there is no canonical DWARF register number with that meaning, it's 277 left unchanged (callers usually initialize with (Dwarf_Word) -1). 278 This value is not used by CFI per se. 279 280 Function returns 0 on success and -1 for error or unsupported by the 281 backend. */ 282 extern int ebl_abi_cfi (Ebl *ebl, Dwarf_CIE *abi_info) 283 __nonnull_attribute__ (2); 284 285 /* ELF string table handling. */ 286 struct Ebl_Strtab; 287 struct Ebl_Strent; 288 289 /* Create new ELF string table object in memory. */ 290 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr); 291 292 /* Free resources allocated for ELF string table ST. */ 293 extern void ebl_strtabfree (struct Ebl_Strtab *st); 294 295 /* Add string STR (length LEN is != 0) to ELF string table ST. */ 296 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st, 297 const char *str, size_t len); 298 299 /* Finalize string table ST and store size and memory location information 300 in DATA. */ 301 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data); 302 303 /* Get offset in string table for string associated with SE. */ 304 extern size_t ebl_strtaboffset (struct Ebl_Strent *se); 305 306 /* Return the string associated with SE. */ 307 extern const char *ebl_string (struct Ebl_Strent *se); 308 309 310 /* ELF wide char string table handling. */ 311 struct Ebl_WStrtab; 312 struct Ebl_WStrent; 313 314 /* Create new ELF wide char string table object in memory. */ 315 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr); 316 317 /* Free resources allocated for ELF wide char string table ST. */ 318 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st); 319 320 /* Add string STR (length LEN is != 0) to ELF string table ST. */ 321 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st, 322 const wchar_t *str, size_t len); 323 324 /* Finalize string table ST and store size and memory location information 325 in DATA. */ 326 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data); 327 328 /* Get offset in wide char string table for string associated with SE. */ 329 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se); 330 331 332 /* Generic string table handling. */ 333 struct Ebl_GStrtab; 334 struct Ebl_GStrent; 335 336 /* Create new string table object in memory. */ 337 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr); 338 339 /* Free resources allocated for string table ST. */ 340 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st); 341 342 /* Add string STR (length LEN is != 0) to string table ST. */ 343 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st, 344 const char *str, size_t len); 345 346 /* Finalize string table ST and store size and memory location information 347 in DATA. */ 348 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data); 349 350 /* Get offset in wide char string table for string associated with SE. */ 351 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se); 352 353 354 /* Register map info. */ 355 typedef struct 356 { 357 Dwarf_Half offset; /* Byte offset in register data block. */ 358 Dwarf_Half regno; /* DWARF register number. */ 359 uint8_t bits; /* Bits of data for one register. */ 360 uint8_t pad; /* Bytes of padding after register's data. */ 361 Dwarf_Half count; /* Consecutive register numbers here. */ 362 bool pc_register; 363 } Ebl_Register_Location; 364 365 /* Non-register data items in core notes. */ 366 typedef struct 367 { 368 const char *name; /* Printable identifier. */ 369 const char *group; /* Identifier for category of related items. */ 370 Dwarf_Half offset; /* Byte offset in note data. */ 371 Dwarf_Half count; 372 Elf_Type type; 373 char format; 374 bool thread_identifier; 375 bool pc_register; 376 } Ebl_Core_Item; 377 378 /* Describe the format of a core file note with the given header and NAME. 379 NAME is not guaranteed terminated, it's NHDR->n_namesz raw bytes. */ 380 extern int ebl_core_note (Ebl *ebl, const GElf_Nhdr *nhdr, const char *name, 381 GElf_Word *regs_offset, size_t *nregloc, 382 const Ebl_Register_Location **reglocs, 383 size_t *nitems, const Ebl_Core_Item **items) 384 __nonnull_attribute__ (1, 2, 3, 4, 5, 6, 7, 8); 385 386 /* Describe the auxv type number. */ 387 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type, 388 const char **name, const char **format) 389 __nonnull_attribute__ (1, 3, 4); 390 391 /* Callback type for ebl_set_initial_registers_tid. 392 Register -1 is mapped to PC (if arch PC has no DWARF number). 393 If FIRSTREG is -1 then NREGS has to be 1. */ 394 typedef bool (ebl_tid_registers_t) (int firstreg, unsigned nregs, 395 const Dwarf_Word *regs, void *arg) 396 __nonnull_attribute__ (3); 397 398 /* Callback to fetch process data from live TID. 399 EBL architecture has to have EBL_FRAME_NREGS > 0, otherwise the 400 backend doesn't support unwinding and this function call may crash. */ 401 extern bool ebl_set_initial_registers_tid (Ebl *ebl, 402 pid_t tid, 403 ebl_tid_registers_t *setfunc, 404 void *arg) 405 __nonnull_attribute__ (1, 3); 406 407 /* Number of registers to allocate for ebl_set_initial_registers_tid. 408 EBL architecture can unwind iff EBL_FRAME_NREGS > 0. */ 409 extern size_t ebl_frame_nregs (Ebl *ebl) 410 __nonnull_attribute__ (1); 411 412 /* Mask to use for function symbol or unwind return addresses in case 413 the architecture adds some extra non-address bits to it. This is 414 different from ebl_resolve_sym_value which only works for actual 415 symbol addresses (in non-ET_REL files) that might resolve to an 416 address in a different section. ebl_func_addr_mask is called to 417 turn a given function value into the a real address or offset (the 418 original value might not be a real address). This works for all 419 cases where an actual function address (or offset in ET_REL symbol 420 tables) is needed. */ 421 extern GElf_Addr ebl_func_addr_mask (Ebl *ebl); 422 423 /* Convert *REGNO as is in DWARF to a lower range suitable for 424 Dwarf_Frame->REGS indexing. */ 425 extern bool ebl_dwarf_to_regno (Ebl *ebl, unsigned *regno) 426 __nonnull_attribute__ (1, 2); 427 428 /* Modify PC as fetched from inferior data into valid PC. */ 429 extern void ebl_normalize_pc (Ebl *ebl, Dwarf_Addr *pc) 430 __nonnull_attribute__ (1, 2); 431 432 /* Callback type for ebl_unwind's parameter getfunc. */ 433 typedef bool (ebl_tid_registers_get_t) (int firstreg, unsigned nregs, 434 Dwarf_Word *regs, void *arg) 435 __nonnull_attribute__ (3); 436 437 /* Callback type for ebl_unwind's parameter readfunc. */ 438 typedef bool (ebl_pid_memory_read_t) (Dwarf_Addr addr, Dwarf_Word *data, 439 void *arg) 440 __nonnull_attribute__ (3); 441 442 /* Get previous frame state for an existing frame state. Method is called only 443 if unwinder could not find CFI for current PC. PC is for the 444 existing frame. SETFUNC sets register in the previous frame. GETFUNC gets 445 register from the existing frame. Note that GETFUNC vs. SETFUNC act on 446 a disjunct set of registers. READFUNC reads memory. ARG has to be passed 447 for SETFUNC, GETFUNC and READFUNC. *SIGNAL_FRAMEP is initialized to false, 448 it can be set to true if existing frame is a signal frame. SIGNAL_FRAMEP is 449 never NULL. */ 450 extern bool ebl_unwind (Ebl *ebl, Dwarf_Addr pc, ebl_tid_registers_t *setfunc, 451 ebl_tid_registers_get_t *getfunc, 452 ebl_pid_memory_read_t *readfunc, void *arg, 453 bool *signal_framep) 454 __nonnull_attribute__ (1, 3, 4, 5, 7); 455 456 /* Returns true if the value can be resolved to an address in an 457 allocated section, which will be returned in *ADDR 458 (e.g. function descriptor resolving) */ 459 extern bool ebl_resolve_sym_value (Ebl *ebl, GElf_Addr *addr) 460 __nonnull_attribute__ (2); 461 462 #ifdef __cplusplus 463 } 464 #endif 465 466 #endif /* libebl.h */ 467