1 /* Interface for libebl. 2 Copyright (C) 2000-2010, 2013, 2014, 2015, 2016, 2017 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) __pure_attribute__; 77 78 /* Get ELF class. */ 79 extern int ebl_get_elfclass (Ebl *ebl) __pure_attribute__; 80 81 /* Get ELF data encoding. */ 82 extern int ebl_get_elfdata (Ebl *ebl) __pure_attribute__; 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_reloc_type_name (Ebl *ebl, int reloc, 93 char *buf, size_t len); 94 95 /* Check relocation type. */ 96 extern bool ebl_reloc_type_check (Ebl *ebl, int reloc); 97 98 /* Check relocation type use. */ 99 extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc); 100 101 /* Check if relocation type is for simple absolute relocations. 102 Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM. 103 If the relocation type is an ADD or SUB relocation, set *ADDSUB to 1 or -1, 104 resp. */ 105 extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc, int *addsub); 106 107 /* Return true if the symbol type is that referencing the GOT. E.g., 108 R_386_GOTPC. */ 109 extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc); 110 111 /* Return segment type name. */ 112 extern const char *ebl_segment_type_name (Ebl *ebl, int segment, 113 char *buf, size_t len); 114 115 /* Return section type name. */ 116 extern const char *ebl_section_type_name (Ebl *ebl, int section, 117 char *buf, size_t len); 118 119 /* Return section name. */ 120 extern const char *ebl_section_name (Ebl *ebl, int section, int xsection, 121 char *buf, size_t len, 122 const char *scnnames[], size_t shnum); 123 124 /* Return machine flag names. */ 125 extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags, 126 char *buf, size_t len); 127 128 /* Check whether machine flag is valid. */ 129 extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags); 130 131 /* Check whether SHF_MASKPROC flags are valid. */ 132 extern bool ebl_machine_section_flag_check (Ebl *ebl, GElf_Xword flags); 133 134 /* Check whether the section with the given index, header, and name 135 is a special machine section that is valid despite a combination 136 of flags or other details that are not generically valid. */ 137 extern bool ebl_check_special_section (Ebl *ebl, int ndx, 138 const GElf_Shdr *shdr, const char *name); 139 140 /* Return symbol type name. */ 141 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol, 142 char *buf, size_t len); 143 144 /* Return symbol binding name. */ 145 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding, 146 char *buf, size_t len); 147 148 /* Return dynamic tag name. */ 149 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag, 150 char *buf, size_t len); 151 152 /* Check dynamic tag. */ 153 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag); 154 155 /* Check whether given symbol's st_value and st_size are OK despite failing 156 normal checks. */ 157 extern bool ebl_check_special_symbol (Ebl *ebl, 158 const GElf_Sym *sym, const char *name, 159 const GElf_Shdr *destshdr); 160 161 /* Check if this is a data marker symbol. e.g. '$d' symbols for ARM. */ 162 extern bool ebl_data_marker_symbol (Ebl *ebl, const GElf_Sym *sym, 163 const char *sname); 164 165 /* Check whether only valid bits are set on the st_other symbol flag. */ 166 extern bool ebl_check_st_other_bits (Ebl *ebl, unsigned char st_other); 167 168 /* Return symbolic representation of OS ABI. */ 169 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len); 170 171 172 /* Return name of the note section type for a core file. */ 173 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf, 174 size_t len); 175 176 /* Return name of the note section type for an object file. */ 177 extern const char *ebl_object_note_type_name (Ebl *ebl, const char *name, 178 uint32_t type, GElf_Word descsz, 179 char *buf, size_t len); 180 181 /* Print information about object note if available. */ 182 extern void ebl_object_note (Ebl *ebl, uint32_t namesz, const char *name, 183 uint32_t type, uint32_t descsz, const char *desc); 184 185 /* Check whether an attribute in a .gnu_attributes section is recognized. 186 Fills in *TAG_NAME with the name for this tag. 187 If VALUE is a known value for that tag, also fills in *VALUE_NAME. */ 188 extern bool ebl_check_object_attribute (Ebl *ebl, const char *vendor, 189 int tag, uint64_t value, 190 const char **tag_name, 191 const char **value_name); 192 193 /* Check whether a section type is a valid reloc target. */ 194 extern bool ebl_check_reloc_target_type (Ebl *ebl, Elf64_Word sh_type); 195 196 197 /* Check section name for being that of a debug informatino section. */ 198 extern bool ebl_debugscn_p (Ebl *ebl, const char *name); 199 200 /* Check whether given relocation is a copy relocation. */ 201 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc); 202 203 /* Check whether given relocation is a no-op relocation. */ 204 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc); 205 206 /* Check whether given relocation is a relative relocation. */ 207 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc); 208 209 /* Check whether section should be stripped. */ 210 extern bool ebl_section_strip_p (Ebl *ebl, 211 const GElf_Shdr *shdr, const char *name, 212 bool remove_comment, bool only_remove_debug); 213 214 /* Check if backend uses a bss PLT in this file. */ 215 extern bool ebl_bss_plt_p (Ebl *ebl); 216 217 /* Return size of entry in SysV-style hash table. */ 218 extern int ebl_sysvhash_entrysize (Ebl *ebl); 219 220 /* Return location expression to find return value given a 221 DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing 222 function itself (whose DW_AT_type attribute describes its return type). 223 Returns -1 for a libdw error (see dwarf_errno). 224 Returns -2 for an unrecognized type formation. 225 Returns zero if the function has no return value (e.g. "void" in C). 226 Otherwise, *LOCOPS gets a location expression to find the return value, 227 and returns the number of operations in the expression. The pointer is 228 permanently allocated at least as long as the Ebl handle is open. */ 229 extern int ebl_return_value_location (Ebl *ebl, 230 Dwarf_Die *functypedie, 231 const Dwarf_Op **locops); 232 233 /* Fill in register information given DWARF register numbers. 234 If NAME is null, return the maximum REGNO + 1 that has a name. 235 Otherwise, store in NAME the name for DWARF register number REGNO 236 and return the number of bytes written (including '\0' terminator). 237 Return -1 if NAMELEN is too short or REGNO is negative or too large. 238 Return 0 if REGNO is unused (a gap in the DWARF number assignment). 239 On success, set *SETNAME to a description like "integer" or "FPU" 240 fit for "%s registers" title display, and *PREFIX to the string 241 that precedes NAME in canonical assembler syntax (e.g. "%" or "$"). 242 The NAME string contains identifier characters only (maybe just digits). */ 243 extern ssize_t ebl_register_info (Ebl *ebl, 244 int regno, char *name, size_t namelen, 245 const char **prefix, const char **setname, 246 int *bits, int *type); 247 248 /* Fill in the DWARF register numbers for the registers used in system calls. 249 The SP and PC are what kernel reports call the user stack pointer and PC. 250 The CALLNO and ARGS are the system call number and incoming arguments. 251 Each of these is filled with the DWARF register number corresponding, 252 or -1 if there is none. Returns zero when the information is available. */ 253 extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc, 254 int *callno, int args[6]); 255 256 /* Supply the ABI-specified state of DWARF CFI before CIE initial programs. 257 258 The DWARF 3.0 spec says that the default initial states of all registers 259 are "undefined", unless otherwise specified by the machine/compiler ABI. 260 261 This default is wrong for every machine with the CFI generated by GCC. 262 The EH unwinder does not really distinguish "same_value" and "undefined", 263 since it doesn't matter for unwinding (in either case there is no change 264 to make for that register). GCC generates CFI that says nothing at all 265 about registers it hasn't spilled somewhere. For our unwinder to give 266 the true story, the backend must supply an initial state that uses 267 "same_value" rules for all the callee-saves registers. 268 269 This can fill in the initial_instructions, initial_instructions_end 270 members of *ABI_INFO to point at a CFI instruction stream to process 271 before each CIE's initial instructions. It should set the 272 data_alignment_factor member if it affects the initial instructions. 273 274 The callback should not use the register rules DW_CFA_expression or 275 DW_CFA_val_expression. Defining the CFA using DW_CFA_def_cfa_expression 276 is allowed. This is an implementation detail since register rules 277 store expressions as offsets from the .eh_frame or .debug_frame data. 278 279 As a shorthand for some common cases, for this instruction stream 280 we overload some CFI instructions that cannot be used in a CIE: 281 282 DW_CFA_restore -- Change default rule for all unmentioned 283 registers from undefined to same_value. 284 285 This function can also fill in ABI_INFO->return_address_register with the 286 DWARF register number that identifies the actual PC in machine state. 287 If there is no canonical DWARF register number with that meaning, it's 288 left unchanged (callers usually initialize with (Dwarf_Word) -1). 289 This value is not used by CFI per se. 290 291 Function returns 0 on success and -1 for error or unsupported by the 292 backend. */ 293 extern int ebl_abi_cfi (Ebl *ebl, Dwarf_CIE *abi_info) 294 __nonnull_attribute__ (2); 295 296 /* Register map info. */ 297 typedef struct 298 { 299 Dwarf_Half offset; /* Byte offset in register data block. */ 300 Dwarf_Half regno; /* DWARF register number. */ 301 uint8_t bits; /* Bits of data for one register. */ 302 uint8_t pad; /* Bytes of padding after register's data. */ 303 Dwarf_Half count; /* Consecutive register numbers here. */ 304 bool pc_register; 305 } Ebl_Register_Location; 306 307 /* Non-register data items in core notes. */ 308 typedef struct 309 { 310 const char *name; /* Printable identifier. */ 311 const char *group; /* Identifier for category of related items. */ 312 Dwarf_Half offset; /* Byte offset in note data. */ 313 Dwarf_Half count; 314 Elf_Type type; 315 char format; 316 bool thread_identifier; 317 bool pc_register; 318 } Ebl_Core_Item; 319 320 /* Describe the format of a core file note with the given header and NAME. 321 NAME is not guaranteed terminated, it's NHDR->n_namesz raw bytes. */ 322 extern int ebl_core_note (Ebl *ebl, const GElf_Nhdr *nhdr, 323 const char *name, const char *desc, 324 GElf_Word *regs_offset, size_t *nregloc, 325 const Ebl_Register_Location **reglocs, 326 size_t *nitems, const Ebl_Core_Item **items) 327 __nonnull_attribute__ (1, 2, 3, 4, 5, 6, 7, 8); 328 329 /* Describe the auxv type number. */ 330 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type, 331 const char **name, const char **format) 332 __nonnull_attribute__ (1, 3, 4); 333 334 /* Callback type for ebl_set_initial_registers_tid. 335 Register -1 is mapped to PC (if arch PC has no DWARF number). 336 If FIRSTREG is -1 then NREGS has to be 1. */ 337 typedef bool (ebl_tid_registers_t) (int firstreg, unsigned nregs, 338 const Dwarf_Word *regs, void *arg) 339 __nonnull_attribute__ (3); 340 341 /* Callback to fetch process data from live TID. 342 EBL architecture has to have EBL_FRAME_NREGS > 0, otherwise the 343 backend doesn't support unwinding and this function call may crash. */ 344 extern bool ebl_set_initial_registers_tid (Ebl *ebl, 345 pid_t tid, 346 ebl_tid_registers_t *setfunc, 347 void *arg) 348 __nonnull_attribute__ (1, 3); 349 350 /* Number of registers to allocate for ebl_set_initial_registers_tid. 351 EBL architecture can unwind iff EBL_FRAME_NREGS > 0. */ 352 extern size_t ebl_frame_nregs (Ebl *ebl) 353 __nonnull_attribute__ (1); 354 355 /* Offset to apply to the value of the return_address_register, as 356 fetched from a Dwarf CFI. This is used by some backends, where the 357 return_address_register actually contains the call address. */ 358 extern int ebl_ra_offset (Ebl *ebl) 359 __nonnull_attribute__ (1); 360 361 /* Mask to use for function symbol or unwind return addresses in case 362 the architecture adds some extra non-address bits to it. This is 363 different from ebl_resolve_sym_value which only works for actual 364 symbol addresses (in non-ET_REL files) that might resolve to an 365 address in a different section. ebl_func_addr_mask is called to 366 turn a given function value into the a real address or offset (the 367 original value might not be a real address). This works for all 368 cases where an actual function address (or offset in ET_REL symbol 369 tables) is needed. */ 370 extern GElf_Addr ebl_func_addr_mask (Ebl *ebl); 371 372 /* Convert *REGNO as is in DWARF to a lower range suitable for 373 Dwarf_Frame->REGS indexing. */ 374 extern bool ebl_dwarf_to_regno (Ebl *ebl, unsigned *regno) 375 __nonnull_attribute__ (1, 2); 376 377 /* Modify PC as fetched from inferior data into valid PC. */ 378 extern void ebl_normalize_pc (Ebl *ebl, Dwarf_Addr *pc) 379 __nonnull_attribute__ (1, 2); 380 381 /* Callback type for ebl_unwind's parameter getfunc. */ 382 typedef bool (ebl_tid_registers_get_t) (int firstreg, unsigned nregs, 383 Dwarf_Word *regs, void *arg) 384 __nonnull_attribute__ (3); 385 386 /* Callback type for ebl_unwind's parameter readfunc. */ 387 typedef bool (ebl_pid_memory_read_t) (Dwarf_Addr addr, Dwarf_Word *data, 388 void *arg) 389 __nonnull_attribute__ (3); 390 391 /* Get previous frame state for an existing frame state. Method is called only 392 if unwinder could not find CFI for current PC. PC is for the 393 existing frame. SETFUNC sets register in the previous frame. GETFUNC gets 394 register from the existing frame. Note that GETFUNC vs. SETFUNC act on 395 a disjunct set of registers. READFUNC reads memory. ARG has to be passed 396 for SETFUNC, GETFUNC and READFUNC. *SIGNAL_FRAMEP is initialized to false, 397 it can be set to true if existing frame is a signal frame. SIGNAL_FRAMEP is 398 never NULL. */ 399 extern bool ebl_unwind (Ebl *ebl, Dwarf_Addr pc, ebl_tid_registers_t *setfunc, 400 ebl_tid_registers_get_t *getfunc, 401 ebl_pid_memory_read_t *readfunc, void *arg, 402 bool *signal_framep) 403 __nonnull_attribute__ (1, 3, 4, 5, 7); 404 405 /* Returns true if the value can be resolved to an address in an 406 allocated section, which will be returned in *ADDR 407 (e.g. function descriptor resolving) */ 408 extern bool ebl_resolve_sym_value (Ebl *ebl, GElf_Addr *addr) 409 __nonnull_attribute__ (2); 410 411 #ifdef __cplusplus 412 } 413 #endif 414 415 #endif /* libebl.h */ 416