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