libebl/libebl.h

   1 /* Interface for libebl.
   2    Copyright (C) 2000-2010 Red Hat, Inc.
   3    This file is part of Red Hat elfutils.
   4
   5    Red Hat elfutils is free software; you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by the
   7    Free Software Foundation; version 2 of the License.
   8
   9    Red Hat elfutils is distributed in the hope that it will be useful, but
  10    WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12    General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License along
  15    with Red Hat elfutils; if not, write to the Free Software Foundation,
  16    Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA.
  17
  18    In addition, as a special exception, Red Hat, Inc. gives You the
  19    additional right to link the code of Red Hat elfutils with code licensed
  20    under any Open Source Initiative certified open source license
  21    (http://www.opensource.org/licenses/index.php) which requires the
  22    distribution of source code with any binary distribution and to
  23    distribute linked combinations of the two.  Non-GPL Code permitted under
  24    this exception must only link to the code of Red Hat elfutils through
  25    those well defined interfaces identified in the file named EXCEPTION
  26    found in the source code files (the "Approved Interfaces").  The files
  27    of Non-GPL Code may instantiate templates or use macros or inline
  28    functions from the Approved Interfaces without causing the resulting
  29    work to be covered by the GNU General Public License.  Only Red Hat,
  30    Inc. may make changes or additions to the list of Approved Interfaces.
  31    Red Hat's grant of this exception is conditioned upon your not adding
  32    any new exceptions.  If you wish to add a new Approved Interface or
  33    exception, please contact Red Hat.  You must obey the GNU General Public
  34    License in all respects for all of the Red Hat elfutils code and other
  35    code used in conjunction with Red Hat elfutils except the Non-GPL Code
  36    covered by this exception.  If you modify this file, you may extend this
  37    exception to your version of the file, but you are not obligated to do
  38    so.  If you do not wish to provide this exception without modification,
  39    you must delete this exception statement from your version and license
  40    this file solely under the GPL without exception.
  41
  42    Red Hat elfutils is an included package of the Open Invention Network.
  43    An included package of the Open Invention Network is a package for which
  44    Open Invention Network licensees cross-license their patents.  No patent
  45    license is granted, either expressly or impliedly, by designation as an
  46    included package.  Should you wish to participate in the Open Invention
  47    Network licensing program, please visit www.openinventionnetwork.com
  48    <http://www.openinventionnetwork.com>.  */
  49
  50 #ifndef _LIBEBL_H
  51 #define _LIBEBL_H 1
  52
  53 #include <gelf.h>
  54 #include "libdw.h"
  55 #include <stdbool.h>
  56 #include <stddef.h>
  57 #include <stdint.h>
  58
  59 #include "elf-knowledge.h"
  60
  61
  62 /* Opaque type for the handle.  */
  63 typedef struct ebl Ebl;
  64
  65
  66 #ifdef __cplusplus
  67 extern "C" {
  68 #endif
  69
  70 /* Get backend handle for object associated with ELF handle.  */
  71 extern Ebl *ebl_openbackend (Elf *elf);
  72 /* Similar but without underlying ELF file.  */
  73 extern Ebl *ebl_openbackend_machine (GElf_Half machine);
  74 /* Similar but with emulation name given.  */
  75 extern Ebl *ebl_openbackend_emulation (const char *emulation);
  76
  77 /* Free resources allocated for backend handle.  */
  78 extern void ebl_closebackend (Ebl *bh);
  79
  80
  81 /* Information about the descriptor.  */
  82
  83 /* Get ELF machine.  */
  84 extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__));
  85
  86 /* Get ELF class.  */
  87 extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__));
  88
  89 /* Get ELF data encoding.  */
  90 extern int ebl_get_elfdata (Ebl *ebl) __attribute__ ((__pure__));
  91
  92
  93 /* Function to call the callback functions including default ELF
  94    handling.  */
  95
  96 /* Return backend name.  */
  97 extern const char *ebl_backend_name (Ebl *ebl);
  98
  99 /* Return relocation type name.  */
 100 extern const char *ebl_object_type_name (Ebl *ebl, int object,
 101                                          char *buf, size_t len);
 102
 103 /* Return relocation type name.  */
 104 extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc,
 105                                         char *buf, size_t len);
 106
 107 /* Check relocation type.  */
 108 extern bool ebl_reloc_type_check (Ebl *ebl, int reloc);
 109
 110 /* Check relocation type use.  */
 111 extern bool ebl_reloc_valid_use (Ebl *ebl, int reloc);
 112
 113 /* Check if relocation type is for simple absolute relocations.
 114    Return ELF_T_{BYTE,HALF,SWORD,SXWORD} for a simple type, else ELF_T_NUM.  */
 115 extern Elf_Type ebl_reloc_simple_type (Ebl *ebl, int reloc);
 116
 117 /* Return true if the symbol type is that referencing the GOT.  E.g.,
 118    R_386_GOTPC.  */
 119 extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc);
 120
 121 /* Return segment type name.  */
 122 extern const char *ebl_segment_type_name (Ebl *ebl, int segment,
 123                                           char *buf, size_t len);
 124
 125 /* Return section type name.  */
 126 extern const char *ebl_section_type_name (Ebl *ebl, int section,
 127                                           char *buf, size_t len);
 128
 129 /* Return section name.  */
 130 extern const char *ebl_section_name (Ebl *ebl, int section, int xsection,
 131                                      char *buf, size_t len,
 132                                      const char *scnnames[], size_t shnum);
 133
 134 /* Return machine flag names.  */
 135 extern const char *ebl_machine_flag_name (Ebl *ebl, GElf_Word flags,
 136                                           char *buf, size_t len);
 137
 138 /* Check whether machine flag is valid.  */
 139 extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags);
 140
 141 /* Check whether SHF_MASKPROC flags are valid.  */
 142 extern bool ebl_machine_section_flag_check (Ebl *ebl, GElf_Xword flags);
 143
 144 /* Check whether the section with the given index, header, and name
 145    is a special machine section that is valid despite a combination
 146    of flags or other details that are not generically valid.  */
 147 extern bool ebl_check_special_section (Ebl *ebl, int ndx,
 148                                        const GElf_Shdr *shdr, const char *name);
 149
 150 /* Return symbol type name.  */
 151 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol,
 152                                          char *buf, size_t len);
 153
 154 /* Return symbol binding name.  */
 155 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding,
 156                                             char *buf, size_t len);
 157
 158 /* Return dynamic tag name.  */
 159 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag,
 160                                          char *buf, size_t len);
 161
 162 /* Check dynamic tag.  */
 163 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag);
 164
 165 /* Check whether given symbol's st_value and st_size are OK despite failing
 166    normal checks.  */
 167 extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr,
 168                                       const GElf_Sym *sym, const char *name,
 169                                       const GElf_Shdr *destshdr);
 170
 171 /* Check whether only valid bits are set on the st_other symbol flag.  */
 172 extern bool ebl_check_st_other_bits (Ebl *ebl, unsigned char st_other);
 173
 174 /* Return combined section header flags value.  */
 175 extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
 176                                        GElf_Word flags2);
 177
 178 /* Return symbolic representation of OS ABI.  */
 179 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len);
 180
 181
 182 /* Return name of the note section type for a core file.  */
 183 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf,
 184                                             size_t len);
 185
 186 /* Return name of the note section type for an object file.  */
 187 extern const char *ebl_object_note_type_name (Ebl *ebl, const char *name,
 188                                               uint32_t type, char *buf,
 189                                               size_t len);
 190
 191 /* Print information about object note if available.  */
 192 extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type,
 193                              uint32_t descsz, const char *desc);
 194
 195 /* Check whether an attribute in a .gnu_attributes section is recognized.
 196    Fills in *TAG_NAME with the name for this tag.
 197    If VALUE is a known value for that tag, also fills in *VALUE_NAME.  */
 198 extern bool ebl_check_object_attribute (Ebl *ebl, const char *vendor,
 199                                         int tag, uint64_t value,
 200                                         const char **tag_name,
 201                                         const char **value_name);
 202
 203
 204 /* Check section name for being that of a debug informatino section.  */
 205 extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
 206
 207 /* Check whether given relocation is a copy relocation.  */
 208 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
 209
 210 /* Check whether given relocation is a no-op relocation.  */
 211 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc);
 212
 213 /* Check whether given relocation is a relative relocation.  */
 214 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc);
 215
 216 /* Check whether section should be stripped.  */
 217 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
 218                                  const GElf_Shdr *shdr, const char *name,
 219                                  bool remove_comment, bool only_remove_debug);
 220
 221 /* Check if backend uses a bss PLT in this file.  */
 222 extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
 223
 224 /* Return size of entry in SysV-style hash table.  */
 225 extern int ebl_sysvhash_entrysize (Ebl *ebl);
 226
 227 /* Return location expression to find return value given a
 228    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 229    function itself (whose DW_AT_type attribute describes its return type).
 230    Returns -1 for a libdw error (see dwarf_errno).
 231    Returns -2 for an unrecognized type formation.
 232    Returns zero if the function has no return value (e.g. "void" in C).
 233    Otherwise, *LOCOPS gets a location expression to find the return value,
 234    and returns the number of operations in the expression.  The pointer is
 235    permanently allocated at least as long as the Ebl handle is open.  */
 236 extern int ebl_return_value_location (Ebl *ebl,
 237                                       Dwarf_Die *functypedie,
 238                                       const Dwarf_Op **locops);
 239
 240 /* Fill in register information given DWARF register numbers.
 241    If NAME is null, return the maximum REGNO + 1 that has a name.
 242    Otherwise, store in NAME the name for DWARF register number REGNO
 243    and return the number of bytes written (including '\0' terminator).
 244    Return -1 if NAMELEN is too short or REGNO is negative or too large.
 245    Return 0 if REGNO is unused (a gap in the DWARF number assignment).
 246    On success, set *SETNAME to a description like "integer" or "FPU"
 247    fit for "%s registers" title display, and *PREFIX to the string
 248    that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
 249    The NAME string contains identifier characters only (maybe just digits).  */
 250 extern ssize_t ebl_register_info (Ebl *ebl,
 251                                   int regno, char *name, size_t namelen,
 252                                   const char **prefix, const char **setname,
 253                                   int *bits, int *type);
 254
 255 /* Fill in the DWARF register numbers for the registers used in system calls.
 256    The SP and PC are what kernel reports call the user stack pointer and PC.
 257    The CALLNO and ARGS are the system call number and incoming arguments.
 258    Each of these is filled with the DWARF register number corresponding,
 259    or -1 if there is none.  Returns zero when the information is available.  */
 260 extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc,
 261                             int *callno, int args[6]);
 262
 263 /* Supply the ABI-specified state of DWARF CFI before CIE initial programs.
 264
 265    The DWARF 3.0 spec says that the default initial states of all registers
 266    are "undefined", unless otherwise specified by the machine/compiler ABI.
 267
 268    This default is wrong for every machine with the CFI generated by GCC.
 269    The EH unwinder does not really distinguish "same_value" and "undefined",
 270    since it doesn't matter for unwinding (in either case there is no change
 271    to make for that register).  GCC generates CFI that says nothing at all
 272    about registers it hasn't spilled somewhere.  For our unwinder to give
 273    the true story, the backend must supply an initial state that uses
 274    "same_value" rules for all the callee-saves registers.
 275
 276    This can fill in the initial_instructions, initial_instructions_end
 277    members of *ABI_INFO to point at a CFI instruction stream to process
 278    before each CIE's initial instructions.  It should set the
 279    data_alignment_factor member if it affects the initial instructions.
 280
 281    As a shorthand for some common cases, for this instruction stream
 282    we overload some CFI instructions that cannot be used in a CIE:
 283
 284         DW_CFA_restore          -- Change default rule for all unmentioned
 285                                    registers from undefined to same_value.
 286
 287    This function can also fill in ABI_INFO->return_address_register with the
 288    DWARF register number that identifies the actual PC in machine state.
 289    If there is no canonical DWARF register number with that meaning, it's
 290    left unchanged (callers usually initialize with (Dwarf_Word) -1).
 291    This value is not used by CFI per se.  */
 292 extern int ebl_abi_cfi (Ebl *ebl, Dwarf_CIE *abi_info)
 293   __nonnull_attribute__ (2);
 294
 295 /* ELF string table handling.  */
 296 struct Ebl_Strtab;
 297 struct Ebl_Strent;
 298
 299 /* Create new ELF string table object in memory.  */
 300 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
 301
 302 /* Free resources allocated for ELF string table ST.  */
 303 extern void ebl_strtabfree (struct Ebl_Strtab *st);
 304
 305 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 306 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
 307                                          const char *str, size_t len);
 308
 309 /* Finalize string table ST and store size and memory location information
 310    in DATA.  */
 311 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
 312
 313 /* Get offset in string table for string associated with SE.  */
 314 extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
 315
 316 /* Return the string associated with SE.  */
 317 extern const char *ebl_string (struct Ebl_Strent *se);
 318
 319
 320 /* ELF wide char string table handling.  */
 321 struct Ebl_WStrtab;
 322 struct Ebl_WStrent;
 323
 324 /* Create new ELF wide char string table object in memory.  */
 325 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
 326
 327 /* Free resources allocated for ELF wide char string table ST.  */
 328 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
 329
 330 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 331 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
 332                                            const wchar_t *str, size_t len);
 333
 334 /* Finalize string table ST and store size and memory location information
 335    in DATA.  */
 336 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
 337
 338 /* Get offset in wide char string table for string associated with SE.  */
 339 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
 340
 341
 342 /* Generic string table handling.  */
 343 struct Ebl_GStrtab;
 344 struct Ebl_GStrent;
 345
 346 /* Create new string table object in memory.  */
 347 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
 348
 349 /* Free resources allocated for string table ST.  */
 350 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
 351
 352 /* Add string STR (length LEN is != 0) to string table ST.  */
 353 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
 354                                            const char *str, size_t len);
 355
 356 /* Finalize string table ST and store size and memory location information
 357    in DATA.  */
 358 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
 359
 360 /* Get offset in wide char string table for string associated with SE.  */
 361 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
 362
 363
 364 /* Register map info. */
 365 typedef struct
 366 {
 367   Dwarf_Half offset;            /* Byte offset in register data block.  */
 368   Dwarf_Half regno;             /* DWARF register number.  */
 369   uint8_t bits;                 /* Bits of data for one register.  */
 370   uint8_t pad;                  /* Bytes of padding after register's data.  */
 371   Dwarf_Half count;             /* Consecutive register numbers here.  */
 372 } Ebl_Register_Location;
 373
 374 /* Non-register data items in core notes.  */
 375 typedef struct
 376 {
 377   const char *name;             /* Printable identifier.  */
 378   const char *group;            /* Identifier for category of related items.  */
 379   Dwarf_Half offset;            /* Byte offset in note data.  */
 380   Dwarf_Half count;
 381   Elf_Type type;
 382   char format;
 383   bool thread_identifier;
 384 } Ebl_Core_Item;
 385
 386 /* Describe the format of a core file note with the given header and NAME.
 387    NAME is not guaranteed terminated, it's NHDR->n_namesz raw bytes.  */
 388 extern int ebl_core_note (Ebl *ebl, const GElf_Nhdr *nhdr, const char *name,
 389                           GElf_Word *regs_offset, size_t *nregloc,
 390                           const Ebl_Register_Location **reglocs,
 391                           size_t *nitems, const Ebl_Core_Item **items)
 392   __nonnull_attribute__ (1, 2, 3, 4, 5, 6, 7, 8);
 393
 394 /* Describe the auxv type number.  */
 395 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type,
 396                           const char **name, const char **format)
 397   __nonnull_attribute__ (1, 3, 4);
 398
 399
 400 #ifdef __cplusplus
 401 }
 402 #endif
 403
 404 #endif  /* libebl.h */