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.  */
63typedef struct ebl Ebl;
64
65
66#ifdef __cplusplus
67extern "C" {
68#endif
69
70/* Get backend handle for object associated with ELF handle.  */
71extern Ebl *ebl_openbackend (Elf *elf);
72/* Similar but without underlying ELF file.  */
73extern Ebl *ebl_openbackend_machine (GElf_Half machine);
74/* Similar but with emulation name given.  */
75extern Ebl *ebl_openbackend_emulation (const char *emulation);
76
77/* Free resources allocated for backend handle.  */
78extern void ebl_closebackend (Ebl *bh);
79
80
81/* Information about the descriptor.  */
82
83/* Get ELF machine.  */
84extern int ebl_get_elfmachine (Ebl *ebl) __attribute__ ((__pure__));
85
86/* Get ELF class.  */
87extern int ebl_get_elfclass (Ebl *ebl) __attribute__ ((__pure__));
88
89/* Get ELF data encoding.  */
90extern 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.  */
97extern const char *ebl_backend_name (Ebl *ebl);
98
99/* Return relocation type name.  */
100extern const char *ebl_object_type_name (Ebl *ebl, int object,
101					 char *buf, size_t len);
102
103/* Return relocation type name.  */
104extern const char *ebl_reloc_type_name (Ebl *ebl, int reloc,
105					char *buf, size_t len);
106
107/* Check relocation type.  */
108extern bool ebl_reloc_type_check (Ebl *ebl, int reloc);
109
110/* Check relocation type use.  */
111extern 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.  */
115extern 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.  */
119extern bool ebl_gotpc_reloc_check (Ebl *ebl, int reloc);
120
121/* Return segment type name.  */
122extern const char *ebl_segment_type_name (Ebl *ebl, int segment,
123					  char *buf, size_t len);
124
125/* Return section type name.  */
126extern const char *ebl_section_type_name (Ebl *ebl, int section,
127					  char *buf, size_t len);
128
129/* Return section name.  */
130extern 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.  */
135extern 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.  */
139extern bool ebl_machine_flag_check (Ebl *ebl, GElf_Word flags);
140
141/* Check whether SHF_MASKPROC flags are valid.  */
142extern 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.  */
147extern bool ebl_check_special_section (Ebl *ebl, int ndx,
148				       const GElf_Shdr *shdr, const char *name);
149
150/* Return symbol type name.  */
151extern const char *ebl_symbol_type_name (Ebl *ebl, int symbol,
152					 char *buf, size_t len);
153
154/* Return symbol binding name.  */
155extern const char *ebl_symbol_binding_name (Ebl *ebl, int binding,
156					    char *buf, size_t len);
157
158/* Return dynamic tag name.  */
159extern const char *ebl_dynamic_tag_name (Ebl *ebl, int64_t tag,
160					 char *buf, size_t len);
161
162/* Check dynamic tag.  */
163extern 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.  */
167extern 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/* Return combined section header flags value.  */
172extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
173				       GElf_Word flags2);
174
175/* Return symbolic representation of OS ABI.  */
176extern const char *ebl_osabi_name (Ebl *ebl, int osabi, char *buf, size_t len);
177
178
179/* Return name of the note section type for a core file.  */
180extern const char *ebl_core_note_type_name (Ebl *ebl, uint32_t type, char *buf,
181					    size_t len);
182
183/* Return name of the note section type for an object file.  */
184extern const char *ebl_object_note_type_name (Ebl *ebl, uint32_t type,
185					      char *buf, size_t len);
186
187/* Print information about object note if available.  */
188extern void ebl_object_note (Ebl *ebl, const char *name, uint32_t type,
189			     uint32_t descsz, const char *desc);
190
191/* Check whether an attribute in a .gnu_attributes section is recognized.
192   Fills in *TAG_NAME with the name for this tag.
193   If VALUE is a known value for that tag, also fills in *VALUE_NAME.  */
194extern bool ebl_check_object_attribute (Ebl *ebl, const char *vendor,
195					int tag, uint64_t value,
196					const char **tag_name,
197					const char **value_name);
198
199
200/* Check section name for being that of a debug informatino section.  */
201extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
202
203/* Check whether given relocation is a copy relocation.  */
204extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
205
206/* Check whether given relocation is a no-op relocation.  */
207extern bool ebl_none_reloc_p (Ebl *ebl, int reloc);
208
209/* Check whether given relocation is a relative relocation.  */
210extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc);
211
212/* Check whether section should be stripped.  */
213extern bool ebl_section_strip_p (Ebl *ebl, const GElf_Ehdr *ehdr,
214				 const GElf_Shdr *shdr, const char *name,
215				 bool remove_comment, bool only_remove_debug);
216
217/* Check if backend uses a bss PLT in this file.  */
218extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
219
220/* Return size of entry in SysV-style hash table.  */
221extern int ebl_sysvhash_entrysize (Ebl *ebl);
222
223/* Return location expression to find return value given a
224   DW_TAG_subprogram, DW_TAG_subroutine_type, or similar DIE describing
225   function itself (whose DW_AT_type attribute describes its return type).
226   Returns -1 for a libdw error (see dwarf_errno).
227   Returns -2 for an unrecognized type formation.
228   Returns zero if the function has no return value (e.g. "void" in C).
229   Otherwise, *LOCOPS gets a location expression to find the return value,
230   and returns the number of operations in the expression.  The pointer is
231   permanently allocated at least as long as the Ebl handle is open.  */
232extern int ebl_return_value_location (Ebl *ebl,
233				      Dwarf_Die *functypedie,
234				      const Dwarf_Op **locops);
235
236/* Fill in register information given DWARF register numbers.
237   If NAME is null, return the maximum REGNO + 1 that has a name.
238   Otherwise, store in NAME the name for DWARF register number REGNO
239   and return the number of bytes written (including '\0' terminator).
240   Return -1 if NAMELEN is too short or REGNO is negative or too large.
241   Return 0 if REGNO is unused (a gap in the DWARF number assignment).
242   On success, set *SETNAME to a description like "integer" or "FPU"
243   fit for "%s registers" title display, and *PREFIX to the string
244   that precedes NAME in canonical assembler syntax (e.g. "%" or "$").
245   The NAME string contains identifier characters only (maybe just digits).  */
246extern ssize_t ebl_register_info (Ebl *ebl,
247				  int regno, char *name, size_t namelen,
248				  const char **prefix, const char **setname,
249				  int *bits, int *type);
250
251/* Fill in the DWARF register numbers for the registers used in system calls.
252   The SP and PC are what kernel reports call the user stack pointer and PC.
253   The CALLNO and ARGS are the system call number and incoming arguments.
254   Each of these is filled with the DWARF register number corresponding,
255   or -1 if there is none.  Returns zero when the information is available.  */
256extern int ebl_syscall_abi (Ebl *ebl, int *sp, int *pc,
257			    int *callno, int args[6]);
258
259/* ELF string table handling.  */
260struct Ebl_Strtab;
261struct Ebl_Strent;
262
263/* Create new ELF string table object in memory.  */
264extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
265
266/* Free resources allocated for ELF string table ST.  */
267extern void ebl_strtabfree (struct Ebl_Strtab *st);
268
269/* Add string STR (length LEN is != 0) to ELF string table ST.  */
270extern struct Ebl_Strent *ebl_strtabadd (struct Ebl_Strtab *st,
271					 const char *str, size_t len);
272
273/* Finalize string table ST and store size and memory location information
274   in DATA.  */
275extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
276
277/* Get offset in string table for string associated with SE.  */
278extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
279
280/* Return the string associated with SE.  */
281extern const char *ebl_string (struct Ebl_Strent *se);
282
283
284/* ELF wide char string table handling.  */
285struct Ebl_WStrtab;
286struct Ebl_WStrent;
287
288/* Create new ELF wide char string table object in memory.  */
289extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
290
291/* Free resources allocated for ELF wide char string table ST.  */
292extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
293
294/* Add string STR (length LEN is != 0) to ELF string table ST.  */
295extern struct Ebl_WStrent *ebl_wstrtabadd (struct Ebl_WStrtab *st,
296					   const wchar_t *str, size_t len);
297
298/* Finalize string table ST and store size and memory location information
299   in DATA.  */
300extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
301
302/* Get offset in wide char string table for string associated with SE.  */
303extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
304
305
306/* Generic string table handling.  */
307struct Ebl_GStrtab;
308struct Ebl_GStrent;
309
310/* Create new string table object in memory.  */
311extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
312
313/* Free resources allocated for string table ST.  */
314extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
315
316/* Add string STR (length LEN is != 0) to string table ST.  */
317extern struct Ebl_GStrent *ebl_gstrtabadd (struct Ebl_GStrtab *st,
318					   const char *str, size_t len);
319
320/* Finalize string table ST and store size and memory location information
321   in DATA.  */
322extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
323
324/* Get offset in wide char string table for string associated with SE.  */
325extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
326
327
328/* Register map info. */
329typedef struct
330{
331  Dwarf_Half offset;		/* Byte offset in register data block.  */
332  Dwarf_Half regno;		/* DWARF register number.  */
333  uint8_t bits;			/* Bits of data for one register.  */
334  uint8_t pad;			/* Bytes of padding after register's data.  */
335  Dwarf_Half count;		/* Consecutive register numbers here.  */
336} Ebl_Register_Location;
337
338/* Non-register data items in core notes.  */
339typedef struct
340{
341  const char *name;		/* Printable identifier.  */
342  const char *group;		/* Identifier for category of related items.  */
343  Dwarf_Half offset;		/* Byte offset in note data.  */
344  Dwarf_Half count;
345  Elf_Type type;
346  char format;
347  bool thread_identifier;
348} Ebl_Core_Item;
349
350/* Describe the format of a core file note with type field matching N_TYPE
351   and descriptor size matching DESCSZ.  */
352extern int ebl_core_note (Ebl *ebl, GElf_Word n_type, GElf_Word descsz,
353			  GElf_Word *regs_offset, size_t *nregloc,
354			  const Ebl_Register_Location **reglocs,
355			  size_t *nitems, const Ebl_Core_Item **items)
356  __nonnull_attribute__ (1, 4, 5, 6, 7, 8);
357
358/* Describe the auxv type number.  */
359extern int ebl_auxv_info (Ebl *ebl, GElf_Xword a_type,
360			  const char **name, const char **format)
361  __nonnull_attribute__ (1, 3, 4);
362
363
364#ifdef __cplusplus
365}
366#endif
367
368#endif	/* libebl.h */
369