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