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.  */
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/* Check whether only valid bits are set on the st_other symbol flag.  */
172extern bool ebl_check_st_other_bits (Ebl *ebl, unsigned char st_other);
173
174/* Return combined section header flags value.  */
175extern GElf_Word ebl_sh_flags_combine (Ebl *ebl, GElf_Word flags1,
176				       GElf_Word flags2);
177
178/* Return symbolic representation of OS ABI.  */
179extern 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.  */
183extern 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.  */
187extern 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.  */
192extern 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.  */
198extern 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.  */
205extern bool ebl_debugscn_p (Ebl *ebl, const char *name);
206
207/* Check whether given relocation is a copy relocation.  */
208extern bool ebl_copy_reloc_p (Ebl *ebl, int reloc);
209
210/* Check whether given relocation is a no-op relocation.  */
211extern bool ebl_none_reloc_p (Ebl *ebl, int reloc);
212
213/* Check whether given relocation is a relative relocation.  */
214extern bool ebl_relative_reloc_p (Ebl *ebl, int reloc);
215
216/* Check whether section should be stripped.  */
217extern 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.  */
222extern bool ebl_bss_plt_p (Ebl *ebl, GElf_Ehdr *ehdr);
223
224/* Return size of entry in SysV-style hash table.  */
225extern 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.  */
236extern 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).  */
250extern 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.  */
260extern 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.  */
292extern int ebl_abi_cfi (Ebl *ebl, Dwarf_CIE *abi_info)
293  __nonnull_attribute__ (2);
294
295/* ELF string table handling.  */
296struct Ebl_Strtab;
297struct Ebl_Strent;
298
299/* Create new ELF string table object in memory.  */
300extern struct Ebl_Strtab *ebl_strtabinit (bool nullstr);
301
302/* Free resources allocated for ELF string table ST.  */
303extern void ebl_strtabfree (struct Ebl_Strtab *st);
304
305/* Add string STR (length LEN is != 0) to ELF string table ST.  */
306extern 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.  */
311extern void ebl_strtabfinalize (struct Ebl_Strtab *st, Elf_Data *data);
312
313/* Get offset in string table for string associated with SE.  */
314extern size_t ebl_strtaboffset (struct Ebl_Strent *se);
315
316/* Return the string associated with SE.  */
317extern const char *ebl_string (struct Ebl_Strent *se);
318
319
320/* ELF wide char string table handling.  */
321struct Ebl_WStrtab;
322struct Ebl_WStrent;
323
324/* Create new ELF wide char string table object in memory.  */
325extern struct Ebl_WStrtab *ebl_wstrtabinit (bool nullstr);
326
327/* Free resources allocated for ELF wide char string table ST.  */
328extern void ebl_wstrtabfree (struct Ebl_WStrtab *st);
329
330/* Add string STR (length LEN is != 0) to ELF string table ST.  */
331extern 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.  */
336extern void ebl_wstrtabfinalize (struct Ebl_WStrtab *st, Elf_Data *data);
337
338/* Get offset in wide char string table for string associated with SE.  */
339extern size_t ebl_wstrtaboffset (struct Ebl_WStrent *se);
340
341
342/* Generic string table handling.  */
343struct Ebl_GStrtab;
344struct Ebl_GStrent;
345
346/* Create new string table object in memory.  */
347extern struct Ebl_GStrtab *ebl_gstrtabinit (unsigned int width, bool nullstr);
348
349/* Free resources allocated for string table ST.  */
350extern void ebl_gstrtabfree (struct Ebl_GStrtab *st);
351
352/* Add string STR (length LEN is != 0) to string table ST.  */
353extern 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.  */
358extern void ebl_gstrtabfinalize (struct Ebl_GStrtab *st, Elf_Data *data);
359
360/* Get offset in wide char string table for string associated with SE.  */
361extern size_t ebl_gstrtaboffset (struct Ebl_GStrent *se);
362
363
364/* Register map info. */
365typedef 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.  */
375typedef 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.  */
388extern 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.  */
395extern 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 */
405