libebl/libebl.h

   1 /* Interface for libebl.
   2    Copyright (C) 2000, 2001, 2002, 2004, 2005, 2006, 2007, 2008 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 /* Return symbol type name.  */
 145 extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol,
 146                                          char *buf, size_t len);
 147
 148 /* Return symbol binding name.  */
 149 extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding,
 150                                             char *buf, size_t len);
 151
 152 /* Return dynamic tag name.  */
 153 extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag,
 154                                          char *buf, size_t len);
 155
 156 /* Check dynamic tag.  */
 157 extern bool ebl_dynamic_tag_check (Ebl *ebl, int64_t tag);
 158
 159 /* Check whether given symbol's st_value and st_size are OK despite failing
 160    normal checks.  */
 161 extern bool ebl_check_special_symbol (Ebl *ebl, GElf_Ehdr *ehdr,
 162                                       const GElf_Sym *sym, const char *name,
 163                                       const GElf_Shdr *destshdr);
 164
 165 /* Return combined section header flags value.  */
 166 extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
 167                                        GElf_Word flags2);
 168
 169 /* Return symbolic representation of OS ABI.  */
 170 extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len);
 171
 172
 173 /* Return name of the note section type for a core file.  */
 174 extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf,
 175                                             size_t len);
 176
 177 /* Return name of the note section type for an object file.  */
 178 extern const char *ebl_object_note_type_name (Ebl *ebl, uint32_t type,
 179                                               char *buf, 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
 194 /* Check section name for being that of a debug informatino section.  */
 195 extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
 196
 197 /* Check whether given relocation is a copy relocation.  */
 198 extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
 199
 200 /* Check whether given relocation is a no-op relocation.  */
 201 extern bool ebl_none_reloc_p (Ebl *ebl, int reloc);
 202
 203 /* Check whether given relocation is a relative relocation.  */
 204 extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc);
 205
 206 /* Check whether section should be stripped.  */
 207 extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
 208                                  const GElf_Shdr *shdr, const char *name,
 209                                  bool remove_comment, bool only_remove_debug);
 210
 211 /* Check if backend uses a bss PLT in this file.  */
 212 extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
 213
 214 /* Return size of entry in SysV-style hash table.  */
 215 extern int ebl_sysvhash_entrysize (Ebl *ebl);
 216
 217 /* Return location expression to find return value given a
 218    DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
 219    function itself (whose DW_AT_type attribute describes its return type).
 220    Returns -1 for a libdw error (see dwarf_errno).
 221    Returns -2 for an unrecognized type formation.
 222    Returns zero if the function has no return value (e.g. "void" in C).
 223    Otherwise, *LOCOPS gets a location expression to find the return value,
 224    and returns the number of operations in the expression.  The pointer is
 225    permanently allocated at least as long as the Ebl handle is open.  */
 226 extern int ebl_return_value_location (Ebl *ebl,
 227                                       Dwarf_Die *functypedie,
 228                                       const Dwarf_Op **locops);
 229
 230 /* Fill in register information given DWARF register numbers.
 231    If NAME is null, return the maximum REGNO + 1 that has a name.
 232    Otherwise, store in NAME the name for DWARF register number REGNO
 233    and return the number of bytes written (including '\0' terminator).
 234    Return -1 if NAMELEN is too short or REGNO is negative or too large.
 235    Return 0 if REGNO is unused (a gap in the DWARF number assignment).
 236    On success, set *SETNAME to a description like "integer" or "FPU"
 237    fit for "%s registers" title display, and *PREFIX to the string
 238    that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
 239    The NAME string contains identifier characters only (maybe just digits).  */
 240 extern ssize_t ebl_register_info (Ebl *ebl,
 241                                   int regno, char *name, size_t namelen,
 242                                   const char **prefix, const char **setname,
 243                                   int *bits, int *type);
 244
 245
 246 /* ELF string table handling.  */
 247 struct Ebl_Strtab;
 248 struct Ebl_Strent;
 249
 250 /* Create new ELF string table object in memory.  */
 251 extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
 252
 253 /* Free resources allocated for ELF string table ST.  */
 254 extern void ebl_strtabfree (struct Ebl_Strtab *st);
 255
 256 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 257 extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
 258                                          const char *str, size_t len);
 259
 260 /* Finalize string table ST and store size and memory location information
 261    in DATA.  */
 262 extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
 263
 264 /* Get offset in string table for string associated with SE.  */
 265 extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
 266
 267 /* Return the string associated with SE.  */
 268 extern const char *ebl_string (struct Ebl_Strent *se);
 269
 270
 271 /* ELF wide char string table handling.  */
 272 struct Ebl_WStrtab;
 273 struct Ebl_WStrent;
 274
 275 /* Create new ELF wide char string table object in memory.  */
 276 extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
 277
 278 /* Free resources allocated for ELF wide char string table ST.  */
 279 extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
 280
 281 /* Add string STR (length LEN is != 0) to ELF string table ST.  */
 282 extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
 283                                            const wchar_t *str, size_t len);
 284
 285 /* Finalize string table ST and store size and memory location information
 286    in DATA.  */
 287 extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
 288
 289 /* Get offset in wide char string table for string associated with SE.  */
 290 extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
 291
 292
 293 /* Generic string table handling.  */
 294 struct Ebl_GStrtab;
 295 struct Ebl_GStrent;
 296
 297 /* Create new string table object in memory.  */
 298 extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
 299
 300 /* Free resources allocated for string table ST.  */
 301 extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
 302
 303 /* Add string STR (length LEN is != 0) to string table ST.  */
 304 extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
 305                                            const char *str, size_t len);
 306
 307 /* Finalize string table ST and store size and memory location information
 308    in DATA.  */
 309 extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
 310
 311 /* Get offset in wide char string table for string associated with SE.  */
 312 extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
 313
 314
 315 /* Register map info. */
 316 typedef struct
 317 {
 318   Dwarf_Half offset;            /* Byte offset in register data block.  */
 319   Dwarf_Half regno;             /* DWARF register number.  */
 320   uint8_t bits;                 /* Bits of data for one register.  */
 321   uint8_t pad;                  /* Bytes of padding after register's data.  */
 322   Dwarf_Half count;             /* Consecutive register numbers here.  */
 323 } Ebl_Register_Location;
 324
 325 /* Non-register data items in core notes.  */
 326 typedef struct
 327 {
 328   const char *name;             /* Printable identifier.  */
 329   const char *group;            /* Identifier for category of related items.  */
 330   Dwarf_Half offset;            /* Byte offset in note data.  */
 331   Dwarf_Half count;
 332   Elf_Type type;
 333   char format;
 334   bool thread_identifier;
 335 } Ebl_Core_Item;
 336
 337 /* Describe the format of a core file note with type field matching N_TYPE
 338    and descriptor size matching DESCSZ.  */
 339 extern int ebl_core_note (Ebl *ebl, GElf_Word n_type, GElf_Word descsz,
 340                           GElf_Word *regs_offset, size_t *nregloc,
 341                           const Ebl_Register_Location **reglocs,
 342                           size_t *nitems, const Ebl_Core_Item **items)
 343   __nonnull_attribute__ (1, 4, 5, 6, 7, 8);
 344
 345 /* Describe the auxv type number.  */
 346 extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type,
 347                           const char **name, const char **format)
 348   __nonnull_attribute__ (1, 3, 4);
 349
 350
 351 #ifdef __cplusplus
 352 }
 353 #endif
 354
 355 #endif  /* libebl.h */