libebl/libebl.h

   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, char *buf,
 179                                               size_t len);
 180
 181 /* Print information about object note if available.  */
 182 extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type,
 183                              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, const char *name,
 323                           GElf_Word *regs_offset, size_t *nregloc,
 324                           const Ebl_Register_Location **reglocs,
 325                           size_t *nitems, const Ebl_Core_Item **items)
 326   __nonnull_attribute__ (1, 2, 3, 4, 5, 6, 7, 8);
 327
 328 /* Describe the auxv type number.  */
 329 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type,
 330                           const char **name, const char **format)
 331   __nonnull_attribute__ (1, 3, 4);
 332
 333 /* Callback type for ebl_set_initial_registers_tid.
 334    Register -1 is mapped to PC (if arch PC has no DWARF number).
 335    If FIRSTREG is -1 then NREGS has to be 1.  */
 336 typedef bool (ebl_tid_registers_t) (int firstreg, unsigned nregs,
 337                                     const Dwarf_Word *regs, void *arg)
 338   __nonnull_attribute__ (3);
 339
 340 /* Callback to fetch process data from live TID.
 341    EBL architecture has to have EBL_FRAME_NREGS > 0, otherwise the
 342    backend doesn't support unwinding and this function call may crash.  */
 343 extern bool ebl_set_initial_registers_tid (Ebl *ebl,
 344                                            pid_t tid,
 345                                            ebl_tid_registers_t *setfunc,
 346                                            void *arg)
 347   __nonnull_attribute__ (1, 3);
 348
 349 /* Number of registers to allocate for ebl_set_initial_registers_tid.
 350    EBL architecture can unwind iff EBL_FRAME_NREGS > 0.  */
 351 extern size_t ebl_frame_nregs (Ebl *ebl)
 352   __nonnull_attribute__ (1);
 353
 354 /* Offset to apply to the value of the return_address_register, as
 355    fetched from a Dwarf CFI.  This is used by some backends, where the
 356    return_address_register actually contains the call address.  */
 357 extern int ebl_ra_offset (Ebl *ebl)
 358   __nonnull_attribute__ (1);
 359
 360 /* Mask to use for function symbol or unwind return addresses in case
 361    the architecture adds some extra non-address bits to it.  This is
 362    different from ebl_resolve_sym_value which only works for actual
 363    symbol addresses (in non-ET_REL files) that might resolve to an
 364    address in a different section.  ebl_func_addr_mask is called to
 365    turn a given function value into the a real address or offset (the
 366    original value might not be a real address).  This works for all
 367    cases where an actual function address (or offset in ET_REL symbol
 368    tables) is needed.  */
 369 extern GElf_Addr ebl_func_addr_mask (Ebl *ebl);
 370
 371 /* Convert *REGNO as is in DWARF to a lower range suitable for
 372    Dwarf_Frame->REGS indexing.  */
 373 extern bool ebl_dwarf_to_regno (Ebl *ebl, unsigned *regno)
 374   __nonnull_attribute__ (1, 2);
 375
 376 /* Modify PC as fetched from inferior data into valid PC.  */
 377 extern void ebl_normalize_pc (Ebl *ebl, Dwarf_Addr *pc)
 378   __nonnull_attribute__ (1, 2);
 379
 380 /* Callback type for ebl_unwind's parameter getfunc.  */
 381 typedef bool (ebl_tid_registers_get_t) (int firstreg, unsigned nregs,
 382                                         Dwarf_Word *regs, void *arg)
 383   __nonnull_attribute__ (3);
 384
 385 /* Callback type for ebl_unwind's parameter readfunc.  */
 386 typedef bool (ebl_pid_memory_read_t) (Dwarf_Addr addr, Dwarf_Word *data,
 387                                       void *arg)
 388   __nonnull_attribute__ (3);
 389
 390 /* Get previous frame state for an existing frame state.  Method is called only
 391    if unwinder could not find CFI for current PC.  PC is for the
 392    existing frame.  SETFUNC sets register in the previous frame.  GETFUNC gets
 393    register from the existing frame.  Note that GETFUNC vs. SETFUNC act on
 394    a disjunct set of registers.  READFUNC reads memory.  ARG has to be passed
 395    for SETFUNC, GETFUNC and READFUNC.  *SIGNAL_FRAMEP is initialized to false,
 396    it can be set to true if existing frame is a signal frame.  SIGNAL_FRAMEP is
 397    never NULL.  */
 398 extern bool ebl_unwind (Ebl *ebl, Dwarf_Addr pc, ebl_tid_registers_t *setfunc,
 399                         ebl_tid_registers_get_t *getfunc,
 400                         ebl_pid_memory_read_t *readfunc, void *arg,
 401                         bool *signal_framep)
 402   __nonnull_attribute__ (1, 3, 4, 5, 7);
 403
 404 /* Returns true if the value can be resolved to an address in an
 405    allocated section, which will be returned in *ADDR
 406    (e.g. function descriptor resolving)  */
 407 extern bool ebl_resolve_sym_value (Ebl *ebl, GElf_Addr *addr)
 408    __nonnull_attribute__ (2);
 409
 410 #ifdef __cplusplus
 411 }
 412 #endif
 413
 414 #endif  /* libebl.h */