libebl/libebl.h

   1 /* Interface for libebl.
   2    Copyright (C) 2000-2010 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
 183 /* Check section name for being that of a debug informatino section.  */
 184 extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
 185
 186 /* Check whether given relocation is a copy relocation.  */
 187 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
 188
 189 /* Check whether given relocation is a no-op relocation.  */
 190 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc);
 191
 192 /* Check whether given relocation is a relative relocation.  */
 193 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc);
 194
 195 /* Check whether section should be stripped.  */
 196 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
 197                                  const GElf_Shdr *shdr, const char *name,
 198                                  bool remove_comment, bool only_remove_debug);
 199
 200 /* Check if backend uses a bss PLT in this file.  */
 201 extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
 202
 203 /* Return size of entry in SysV-style hash table.  */
 204 extern int ebl_sysvhash_entrysize (Ebl *ebl);
 205
 206 /* Return location expression to find return value given a
 207    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 208    function itself (whose DW_AT_type attribute describes its return type).
 209    Returns -1 for a libdw error (see dwarf_errno).
 210    Returns -2 for an unrecognized type formation.
 211    Returns zero if the function has no return value (e.g. "void" in C).
 212    Otherwise, *LOCOPS gets a location expression to find the return value,
 213    and returns the number of operations in the expression.  The pointer is
 214    permanently allocated at least as long as the Ebl handle is open.  */
 215 extern int ebl_return_value_location (Ebl *ebl,
 216                                       Dwarf_Die *functypedie,
 217                                       const Dwarf_Op **locops);
 218
 219 /* Fill in register information given DWARF register numbers.
 220    If NAME is null, return the maximum REGNO + 1 that has a name.
 221    Otherwise, store in NAME the name for DWARF register number REGNO
 222    and return the number of bytes written (including '\0' terminator).
 223    Return -1 if NAMELEN is too short or REGNO is negative or too large.
 224    Return 0 if REGNO is unused (a gap in the DWARF number assignment).
 225    On success, set *SETNAME to a description like "integer" or "FPU"
 226    fit for "%s registers" title display, and *PREFIX to the string
 227    that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
 228    The NAME string contains identifier characters only (maybe just digits).  */
 229 extern ssize_t ebl_register_info (Ebl *ebl,
 230                                   int regno, char *name, size_t namelen,
 231                                   const char **prefix, const char **setname,
 232                                   int *bits, int *type);
 233
 234 /* Fill in the DWARF register numbers for the registers used in system calls.
 235    The SP and PC are what kernel reports call the user stack pointer and PC.
 236    The CALLNO and ARGS are the system call number and incoming arguments.
 237    Each of these is filled with the DWARF register number corresponding,
 238    or -1 if there is none.  Returns zero when the information is available.  */
 239 extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc,
 240                             int *callno, int args[6]);
 241
 242 /* Supply the ABI-specified state of DWARF CFI before CIE initial programs.
 243
 244    The DWARF 3.0 spec says that the default initial states of all registers
 245    are "undefined", unless otherwise specified by the machine/compiler ABI.
 246
 247    This default is wrong for every machine with the CFI generated by GCC.
 248    The EH unwinder does not really distinguish "same_value" and "undefined",
 249    since it doesn't matter for unwinding (in either case there is no change
 250    to make for that register).  GCC generates CFI that says nothing at all
 251    about registers it hasn't spilled somewhere.  For our unwinder to give
 252    the true story, the backend must supply an initial state that uses
 253    "same_value" rules for all the callee-saves registers.
 254
 255    This can fill in the initial_instructions, initial_instructions_end
 256    members of *ABI_INFO to point at a CFI instruction stream to process
 257    before each CIE's initial instructions.  It should set the
 258    data_alignment_factor member if it affects the initial instructions.
 259
 260    As a shorthand for some common cases, for this instruction stream
 261    we overload some CFI instructions that cannot be used in a CIE:
 262
 263         DW_CFA_restore          -- Change default rule for all unmentioned
 264                                    registers from undefined to same_value.
 265
 266    This function can also fill in ABI_INFO->return_address_register with the
 267    DWARF register number that identifies the actual PC in machine state.
 268    If there is no canonical DWARF register number with that meaning, it's
 269    left unchanged (callers usually initialize with (Dwarf_Word) -1).
 270    This value is not used by CFI per se.  */
 271 extern int ebl_abi_cfi (Ebl *ebl, Dwarf_CIE *abi_info)
 272   __nonnull_attribute__ (2);
 273
 274 /* ELF string table handling.  */
 275 struct Ebl_Strtab;
 276 struct Ebl_Strent;
 277
 278 /* Create new ELF string table object in memory.  */
 279 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
 280
 281 /* Free resources allocated for ELF string table ST.  */
 282 extern void ebl_strtabfree (struct Ebl_Strtab *st);
 283
 284 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 285 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
 286                                          const char *str, size_t len);
 287
 288 /* Finalize string table ST and store size and memory location information
 289    in DATA.  */
 290 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
 291
 292 /* Get offset in string table for string associated with SE.  */
 293 extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
 294
 295 /* Return the string associated with SE.  */
 296 extern const char *ebl_string (struct Ebl_Strent *se);
 297
 298
 299 /* ELF wide char string table handling.  */
 300 struct Ebl_WStrtab;
 301 struct Ebl_WStrent;
 302
 303 /* Create new ELF wide char string table object in memory.  */
 304 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
 305
 306 /* Free resources allocated for ELF wide char string table ST.  */
 307 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
 308
 309 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 310 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
 311                                            const wchar_t *str, size_t len);
 312
 313 /* Finalize string table ST and store size and memory location information
 314    in DATA.  */
 315 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
 316
 317 /* Get offset in wide char string table for string associated with SE.  */
 318 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
 319
 320
 321 /* Generic string table handling.  */
 322 struct Ebl_GStrtab;
 323 struct Ebl_GStrent;
 324
 325 /* Create new string table object in memory.  */
 326 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
 327
 328 /* Free resources allocated for string table ST.  */
 329 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
 330
 331 /* Add string STR (length LEN is != 0) to string table ST.  */
 332 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
 333                                            const char *str, size_t len);
 334
 335 /* Finalize string table ST and store size and memory location information
 336    in DATA.  */
 337 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
 338
 339 /* Get offset in wide char string table for string associated with SE.  */
 340 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
 341
 342
 343 /* Register map info. */
 344 typedef struct
 345 {
 346   Dwarf_Half offset;            /* Byte offset in register data block.  */
 347   Dwarf_Half regno;             /* DWARF register number.  */
 348   uint8_t bits;                 /* Bits of data for one register.  */
 349   uint8_t pad;                  /* Bytes of padding after register's data.  */
 350   Dwarf_Half count;             /* Consecutive register numbers here.  */
 351 } Ebl_Register_Location;
 352
 353 /* Non-register data items in core notes.  */
 354 typedef struct
 355 {
 356   const char *name;             /* Printable identifier.  */
 357   const char *group;            /* Identifier for category of related items.  */
 358   Dwarf_Half offset;            /* Byte offset in note data.  */
 359   Dwarf_Half count;
 360   Elf_Type type;
 361   char format;
 362   bool thread_identifier;
 363 } Ebl_Core_Item;
 364
 365 /* Describe the format of a core file note with the given header and NAME.
 366    NAME is not guaranteed terminated, it's NHDR->n_namesz raw bytes.  */
 367 extern int ebl_core_note (Ebl *ebl, const GElf_Nhdr *nhdr, const char *name,
 368                           GElf_Word *regs_offset, size_t *nregloc,
 369                           const Ebl_Register_Location **reglocs,
 370                           size_t *nitems, const Ebl_Core_Item **items)
 371   __nonnull_attribute__ (1, 2, 3, 4, 5, 6, 7, 8);
 372
 373 /* Describe the auxv type number.  */
 374 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type,
 375                           const char **name, const char **format)
 376   __nonnull_attribute__ (1, 3, 4);
 377
 378
 379 #ifdef __cplusplus
 380 }
 381 #endif
 382
 383 #endif  /* libebl.h */