libebl/libebl.h

   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, GElf_Ehdr *ehdr);
 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 */