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