libdwarf/libdwarf.h

/* Interface for libdwarf.
   Copyright (C) 2000, 2001, 2002 Red Hat, Inc.

   This program is Open Source software; you can redistribute it and/or
   modify it under the terms of the Open Software License version 1.0 as
   published by the Open Source Initiative.

   You should have received a copy of the Open Software License along
   with this program; if not, you may obtain a copy of the Open Software
   License version 1.0 from http://www.opensource.org/licenses/osl.php or
   by writing the Open Source Initiative c/o Lawrence Rosen, Esq.,
   3001 King Ranch Road, Ukiah, CA 95482.   */

#ifndef _LIBDWARF_H
#define _LIBDWARF_H 1

#include <libelf.h>
#include <stdint.h>

/* Basic data types.  */

/* Used for boolean values.  */
typedef int Dwarf_Bool;

/* Numeric values of different sizes.  */
typedef uint8_t Dwarf_Small;
typedef uint16_t Dwarf_Half;
typedef uint64_t Dwarf_Unsigned;
typedef int64_t Dwarf_Signed;

/* Offsets in the debugging sections.  */
typedef uint64_t Dwarf_Off;

/* Program counter value in the target object file.  */
typedef uint64_t Dwarf_Addr;

/* Address in the host process.  */
typedef void *Dwarf_Ptr;


/* Location record.  */
typedef struct
  {
    Dwarf_Small lr_atom;		/* Operation */
    Dwarf_Unsigned lr_number;		/* Operand */
    Dwarf_Unsigned lr_number2;		/* Possible second operand */
    Dwarf_Unsigned lr_offset;		/* Offset in location expression */
  } Dwarf_Loc;


/* Location description.  */
typedef struct
   {
     Dwarf_Addr ld_lopc;		/* Beginning of range */
     Dwarf_Addr ld_hipc;		/* End of range */
     Dwarf_Half ld_cents;		/* Number of location records */
     Dwarf_Loc *ld_s;			/* Array of location records */
  } Dwarf_Locdesc;


/* Error handler function.  */
typedef struct Dwarf_Error_s *Dwarf_Error;	/* Forward declaration.  */
typedef void (*Dwarf_Handler) (Dwarf_Error *, Dwarf_Ptr);

/* Descriptor for block of uninterpreted data.  */
typedef struct
  {
    Dwarf_Unsigned bl_len;
    Dwarf_Ptr bl_data;
  } Dwarf_Block;


/* Descriptor for libdwarf session.  */
typedef struct Dwarf_Debug_s *Dwarf_Debug;

/* Descriptor for DWARF DIE.  */
typedef struct Dwarf_Die_s *Dwarf_Die;

/* Descriptor for DWARF attribute list.  */
typedef struct Dwarf_Attribute_s *Dwarf_Attribute;

/* Descriptor for source lines.  */
typedef struct Dwarf_Line_s *Dwarf_Line;

/* Descriptor for global name.  */
typedef struct Dwarf_Global_s *Dwarf_Global;

/* Descriptor for address range.  */
typedef struct Dwarf_Arange_s *Dwarf_Arange;

/* Descriptor for common information entry.  */
typedef struct Dwarf_Cie_s *Dwarf_Cie;

/* Descriptor for frame descriptor entry.  */
typedef struct Dwarf_Fde_s *Dwarf_Fde;

/* Descriptor for abbreviations.  */
typedef struct Dwarf_Abbrev_s *Dwarf_Abbrev;


/* Return values.  */
enum
  {
    DW_DLV_NO_ENTRY = -1,	/* No error, but no entry.  */
    DW_DLV_OK = 0,		/* Success.  */
    DW_DLV_ERROR = 1,		/* Failure.  */
  };


/* Values for ACCESS parameter of 'dwarf_init' and 'dwarf_elf_init'.  */
enum
  {
    DW_DLC_READ = 0,		/* Read-only access.  */
    DW_DLC_WRITE = 1,		/* Write-only access.  */
    DW_DLC_RDWR = 2		/* Read-write access.  */
  };


/* Open file associates with FD for use with the other functions of
   this library.  Set the error handler and the parameter passed.  */
extern int dwarf_init (int fd, Dwarf_Unsigned access,
		       Dwarf_Handler errhand, Dwarf_Ptr errarg,
		       Dwarf_Debug *dbg, Dwarf_Error *errdesc);

/* Similar to `dwarf_init' but instead of a file descriptor of ELF
   descriptor is passed.  */
extern int dwarf_elf_init (Elf *elf, Dwarf_Unsigned access,
			   Dwarf_Handler errhand, Dwarf_Ptr errarg,
			   Dwarf_Debug *dbg, Dwarf_Error *errdesc);

/* Return ELF handle.  */
extern int dwarf_get_elf_init (Dwarf_Debug dbg, Elf **elf,
			       Dwarf_Error *errdesc);

/* Free resources allocated for debug handle.  */
extern int dwarf_finish (Dwarf_Debug dbg, Dwarf_Error *errdesc);


/* Return information about current and find new compile unit header.  */
extern int dwarf_next_cu_header (Dwarf_Debug dbg,
				 Dwarf_Unsigned *cu_header_length,
				 Dwarf_Half *version_stamp,
				 Dwarf_Unsigned *abbrev_offset,
				 Dwarf_Half *address_size,
				 Dwarf_Unsigned *next_cu_header,
				 Dwarf_Error *errdesc);

/* Return sibling of given DIE.  */
extern int dwarf_siblingof (Dwarf_Debug dbg, Dwarf_Die die,
			    Dwarf_Die *return_sub, Dwarf_Error *errdesc);

/* Return child of DIE.  */
extern int dwarf_child (Dwarf_Die die, Dwarf_Die *return_kid,
			Dwarf_Error *errdesc);

/* Return DIE at given offset.  */
extern int dwarf_offdie (Dwarf_Debug dbg, Dwarf_Off offset,
			 Dwarf_Die *return_die, Dwarf_Error *errdesc);


/* Return tag of DIE.  */
extern int dwarf_tag (Dwarf_Die die, Dwarf_Half *tagval, Dwarf_Error *errdesc);

/* Return offset of DIE in .debug_info section.  */
extern int dwarf_dieoffset (Dwarf_Die die, Dwarf_Off *return_offset,
			    Dwarf_Error *errdesc);

/* Return offset of DIE in compile unit data.  */
extern int dwarf_die_CU_offset (Dwarf_Die die, Dwarf_Off *return_offset,
				Dwarf_Error *errdesc);

/* Return name attribute of DIE.  */
extern int dwarf_diename (Dwarf_Die die, char **return_name,
			  Dwarf_Error *errdesc);

/* Return list of attributes for DIE.  */
extern int dwarf_attrlist (Dwarf_Die die, Dwarf_Attribute **attrbuf,
			   Dwarf_Signed *attrcount, Dwarf_Error *errdesc);

/* Determine whether DIE has attribute specified of given type.  */
extern int dwarf_hasattr (Dwarf_Die die, Dwarf_Half attr,
			  Dwarf_Bool *return_bool, Dwarf_Error *errdesc);

/* Return DIE attribute with specified of given type.  */
extern int dwarf_attr (Dwarf_Die die, Dwarf_Half attr,
		       Dwarf_Attribute *return_attr, Dwarf_Error *errdesc);

/* Return low program counter value associated with die.  */
extern int dwarf_lowpc (Dwarf_Die die, Dwarf_Addr *return_lowpc,
			Dwarf_Error *errdesc);

/* Return high program counter value associated with die.  */
extern int dwarf_highpc (Dwarf_Die die, Dwarf_Addr *return_lowpc,
			 Dwarf_Error *errdesc);

/* Return byte size value associated with die.  */
extern int dwarf_bytesize (Dwarf_Die die, Dwarf_Unsigned *return_size,
			   Dwarf_Error *errdesc);

/* Return bit size value associated with die.  */
extern int dwarf_bitsize (Dwarf_Die die, Dwarf_Unsigned *return_size,
			  Dwarf_Error *errdesc);

/* Return bit offset value associated with die.  */
extern int dwarf_bitoffset (Dwarf_Die die, Dwarf_Unsigned *return_size,
			    Dwarf_Error *errdesc);

/* Return source language associated with die.  */
extern int dwarf_srclang (Dwarf_Die die, Dwarf_Unsigned *return_lang,
			  Dwarf_Error *errdesc);

/* Return source language associated with die.  */
extern int dwarf_arrayorder (Dwarf_Die die, Dwarf_Unsigned *return_order,
			     Dwarf_Error *errdesc);


/* Determine whether attribute has given form.  */
extern int dwarf_hasform (Dwarf_Attribute attr, Dwarf_Half form,
			  Dwarf_Bool *return_hasform, Dwarf_Error *errdesc);

/* Return form of attribute.  */
extern int dwarf_whatform (Dwarf_Attribute attr, Dwarf_Half *return_form,
			   Dwarf_Error *errdesc);

/* Return code of attribute.  */
extern int dwarf_whatattr (Dwarf_Attribute attr, Dwarf_Half *return_attr,
			   Dwarf_Error *errdesc);

/*  Return compile-unit relative offset of reference associated with form.  */
extern int dwarf_formref (Dwarf_Attribute attr, Dwarf_Off *return_offset,
			  Dwarf_Error *errdesc);

/*  Return .debug_info section global offset of reference associated
    with form.  */
extern int dwarf_global_formref (Dwarf_Attribute attr,
				 Dwarf_Off *return_offset,
				 Dwarf_Error *errdesc);

/* Return address represented by attribute.  */
extern int dwarf_formaddr (Dwarf_Attribute attr, Dwarf_Addr *return_addr,
			   Dwarf_Error *errdesc);

/* Return flag represented by attribute.  */
extern int dwarf_formflag (Dwarf_Attribute attr, Dwarf_Bool *return_bool,
			   Dwarf_Error *errdesc);

/* Return unsigned constant represented by attribute.  */
extern int dwarf_formudata (Dwarf_Attribute attr, Dwarf_Unsigned *return_uval,
			    Dwarf_Error *errdesc);

/* Return signed constant represented by attribute.  */
extern int dwarf_formsdata (Dwarf_Attribute attr, Dwarf_Signed *return_uval,
			    Dwarf_Error *errdesc);

/* Return block of uninterpreted data represented by attribute.  */
extern int dwarf_formblock (Dwarf_Attribute attr, Dwarf_Block **return_block,
			    Dwarf_Error *errdesc);

/* Return string represented by attribute.  */
extern int dwarf_formstring (Dwarf_Attribute attr, char **return_string,
			     Dwarf_Error *errdesc);

/* Return location expression list.  */
extern int dwarf_loclist (Dwarf_Attribute attr, Dwarf_Locdesc **llbuf,
			  Dwarf_Signed *listlen, Dwarf_Error *errdesc);


/* Return source lines of compilation unit.  */
extern int dwarf_srclines (Dwarf_Die die, Dwarf_Line **linebuf,
			   Dwarf_Signed *linecount, Dwarf_Error *errdesc);

/* Return files used in compilation unit.  */
extern int dwarf_srcfiles (Dwarf_Die die, char ***srcfiles,
			   Dwarf_Signed *srcfilecount, Dwarf_Error *errdesc);

/* Determine whether line is the beginning of a statement.  */
extern int dwarf_linebeginstatement (Dwarf_Line line, Dwarf_Bool *return_bool,
				     Dwarf_Error *errdesc);

/* Determine whether line is marked as ending a text sequence.  */
extern int dwarf_lineendsequence (Dwarf_Line line, Dwarf_Bool *return_bool,
				  Dwarf_Error *errdesc);

/* Return source statement line number.  */
extern int dwarf_lineno (Dwarf_Line line, Dwarf_Unsigned *return_lineno,
			 Dwarf_Error *errdesc);

/* Return address associate with line.  */
extern int dwarf_lineaddr (Dwarf_Line line, Dwarf_Addr *return_lineaddr,
			   Dwarf_Error *errdesc);

/* Return column at which the statement begins.  */
extern int dwarf_lineoff (Dwarf_Line line, Dwarf_Signed *return_lineoff,
			  Dwarf_Error *errdesc);

/* Return source file for line.  */
extern int dwarf_linesrc (Dwarf_Line line, char **return_linesrc,
			  Dwarf_Error *errdesc);

/* Determine whether line is marked as beginning a basic block.  */
extern int dwarf_lineblock (Dwarf_Line line, Dwarf_Bool *return_bool,
			    Dwarf_Error *errdesc);

/* Determine whether line is marked as ending the prologue.  */
extern int dwarf_lineprologueend (Dwarf_Line line, Dwarf_Bool *return_bool,
				  Dwarf_Error *errdesc);

/* Determine whether line is marked as beginning the epilogue.  */
extern int dwarf_lineepiloguebegin (Dwarf_Line line, Dwarf_Bool *return_bool,
				    Dwarf_Error *errdesc);


/* Return list of global definitions.  */
extern int dwarf_get_globals (Dwarf_Debug dbg, Dwarf_Global **globals,
			      Dwarf_Signed *return_count,
			      Dwarf_Error *errdesc);

/* Return name for global definition.  */
extern int dwarf_globname (Dwarf_Global global, char **return_name,
			   Dwarf_Error *errdesc);

/* Return DIE offset for global definition.  */
extern int dwarf_global_die_offset (Dwarf_Global global,
				    Dwarf_Off *return_offset,
				    Dwarf_Error *errdesc);

/* Return offset of header of compile unit containing the global definition. */
extern int dwarf_global_cu_offset (Dwarf_Global global,
				   Dwarf_Off *return_offset,
				   Dwarf_Error *errdesc);

/* Return name, DIE offset, and offset of the compile unit DIE for the
   global definition.  */
extern int dwarf_global_name_offsets (Dwarf_Global global, char **return_name,
				      Dwarf_Off *die_offset,
				      Dwarf_Off *cu_offset,
				      Dwarf_Error *errdesc);


/* Find start of macro value.  */
extern char *dwarf_find_macro_value_start (char *macro_string);


/* Return string from debug string section.  */
extern int dwarf_get_str (Dwarf_Debug dbg, Dwarf_Off offset, char **string,
			  Dwarf_Signed *returned_str_len,
			  Dwarf_Error *errdesc);


/* Return list address ranges.  */
extern int dwarf_get_aranges (Dwarf_Debug dbg, Dwarf_Arange **aranges,
			      Dwarf_Signed *return_count,
			      Dwarf_Error *errdesc);

/* Find matching range for address.  */
extern int dwarf_get_arange (Dwarf_Arange *aranges,
			     Dwarf_Unsigned arange_count, Dwarf_Addr address,
			     Dwarf_Arange *return_arange,
			     Dwarf_Error *errdesc);

/* Return offset of compile unit DIE containing the range.  */
extern int dwarf_get_cu_die_offset (Dwarf_Arange arange,
				    Dwarf_Off *return_offset,
				    Dwarf_Error *errdesc);

/* Return start, length, and CU DIE offset of range.  */
extern int dwarf_get_arange_info (Dwarf_Arange arange, Dwarf_Addr *start,
				  Dwarf_Unsigned *length,
				  Dwarf_Off *cu_die_offset,
				  Dwarf_Error *errdesc);


/* Frame descriptor handling.  */

/* Get frame descriptions.  GCC version using .eh_frame.  */
extern int dwarf_get_fde_list_eh (Dwarf_Debug dbg, Dwarf_Cie **cie_data,
				  Dwarf_Signed *cie_element_count,
				  Dwarf_Fde **fde_data,
				  Dwarf_Signed *fde_element_count,
				  Dwarf_Error *errdesc);

/* Get CIE of FDE.  */
extern int dwarf_get_cie_of_fde (Dwarf_Fde fde, Dwarf_Cie *return_cie,
				 Dwarf_Error *errdesc);

/* Get information about the function range.  */
extern int dwarf_get_fde_range (Dwarf_Fde fde, Dwarf_Addr *low_pc,
				Dwarf_Unsigned *func_length,
				Dwarf_Ptr *fde_bytes,
				Dwarf_Unsigned *fde_byte_length,
				Dwarf_Off *cie_offset, Dwarf_Signed *cie_index,
				Dwarf_Off *fde_offset, Dwarf_Error *errdesc);

/* Get information about CIE.  */
extern int dwarf_get_cie_info (Dwarf_Cie cie, Dwarf_Unsigned *bytes_in_cie,
			       Dwarf_Small *version, char **augmenter,
			       Dwarf_Unsigned *code_alignment_factor,
			       Dwarf_Signed *data_alignment_factor,
			       Dwarf_Half *return_address_register,
			       Dwarf_Ptr *initial_instructions,
			       Dwarf_Unsigned *initial_instructions_length,
			       Dwarf_Error *errdesc);

/* Get frame construction instructions of FDE.  */
extern int dwarf_get_fde_instr_bytes (Dwarf_Fde fde, Dwarf_Ptr *outinstrs,
				      Dwarf_Unsigned *outlen,
				      Dwarf_Error *errdesc);

/* Get nth frame descriptions.  */
extern int dwarf_get_fde_n (Dwarf_Fde *fde_data, Dwarf_Unsigned fde_index,
			    Dwarf_Fde *returned_fde, Dwarf_Error *errdesc);

/* Find FDE for given address.  */
extern int dwarf_get_fde_at_pc (Dwarf_Fde *fde_data, Dwarf_Addr pc_of_interest,
				Dwarf_Fde *returned_fde, Dwarf_Addr *lopc,
				Dwarf_Addr *hipc, Dwarf_Error *errdesc);


/* Return location list entry.  */
extern int dwarf_get_loclist_entry (Dwarf_Debug dbg, Dwarf_Unsigned offset,
				    Dwarf_Addr *hipc_offset,
				    Dwarf_Addr *lopc_offset, Dwarf_Ptr *data,
				    Dwarf_Unsigned *entry_len,
				    Dwarf_Unsigned *next_entry,
				    Dwarf_Error *errdesc);


/* Get abbreviation record.  */
extern int dwarf_get_abbrev (Dwarf_Debug dbg,
			     Dwarf_Unsigned offset,
			     Dwarf_Abbrev *returned_abbrev,
			     Dwarf_Unsigned *length,
			     Dwarf_Unsigned *attr_count, Dwarf_Error *errdesc);

/* Get tag of abbreviation record.  */
extern int dwarf_get_abbrev_tag (Dwarf_Abbrev abbrev, Dwarf_Half *return_tag,
				 Dwarf_Error *errdesc);

/* Get code of abbreviation record.  */
extern int dwarf_get_abbrev_code (Dwarf_Abbrev abbrev,
				  Dwarf_Unsigned *return_code,
				  Dwarf_Error *errdesc);

/* Get children flag of abbreviation record.  */
extern int dwarf_get_abbrev_children_flag (Dwarf_Abbrev abbrev,
					   Dwarf_Signed *return_flag,
					   Dwarf_Error *errdesc);

/* Get attribute from abbreviation record.  */
extern int dwarf_get_abbrev_entry (Dwarf_Abbrev abbrev, Dwarf_Signed idx,
				   Dwarf_Half *attr_num, Dwarf_Signed *form,
				   Dwarf_Off *offset, Dwarf_Error *errdesc);


/* Memory handling.  */

/* Values for ALLOC_TYPE parameter of 'dwarf_dealloc'.  */
enum
  {
    DW_DLA_NONE = 0,
    DW_DLA_STRING,		/* char* */
    DW_DLA_LOC,			/* Dwarf_Loc */
    DW_DLA_LOCDESC,		/* Dwarf_Locdesc */
    DW_DLA_ELLIST,		/* Dwarf_Ellist */
    DW_DLA_BOUNDS,		/* Dwarf_Bounds */
    DW_DLA_BLOCK,		/* Dwarf_Block */
    DW_DLA_DEBUG,		/* Dwarf_Debug */
    DW_DLA_DIE,			/* Dwarf_Die */
    DW_DLA_LINE,		/* Dwarf_Line */
    DW_DLA_ATTR,		/* Dwarf_Attribute */
    DW_DLA_TYPE,		/* Dwarf_Type */
    DW_DLA_SUBSCR,		/* Dwarf_Subscr */
    DW_DLA_GLOBAL,		/* Dwarf_Global */
    DW_DLA_ERROR,		/* Dwarf_Error */
    DW_DLA_LIST,		/* a list */
    DW_DLA_LINEBUF,		/* Dwarf_Line* */
    DW_DLA_ARANGE,		/* Dwarf_Arange */
    DW_DLA_ABBREV,		/* Dwarf_Abbrev */
    DW_DLA_FRAME_OP,		/* Dwarf_Frame_Op */
    DW_DLA_CIE,			/* Dwarf_Cie */
    DW_DLA_FDE,			/* Dwarf_Fde */
    DW_DLA_LOC_BLOCK,		/* Dwarf_Loc Block */
    DW_DLA_FRAME_BLOCK,		/* Dwarf_Frame Block */
    DW_DLA_FUNC,		/* Dwarf_Func */
    DW_DLA_TYPENAME,		/* Dwarf_Type */
    DW_DLA_VAR,			/* Dwarf_Var */
    DW_DLA_WEAK,		/* Dwarf_Weak */
    DW_DLA_ADDR,		/* Dwarf_Addr sized entries */
  };

/* Deallocate memory.  */
extern void dwarf_dealloc (Dwarf_Debug dbg, Dwarf_Ptr space,
			   Dwarf_Unsigned alloc_type);


/* Determine size of address of the binary.  */
extern int dwarf_get_address_size (Dwarf_Debug dbg, Dwarf_Half *addr_size,
				   Dwarf_Error *errdesc);


/* Return error number.  */
extern Dwarf_Unsigned dwarf_errno (Dwarf_Error errdesc);

/* Return string corresponding to error.  */
extern const char *dwarf_errmsg (Dwarf_Error errdesc);


/* Set new error handler.  */
extern Dwarf_Handler dwarf_seterrhand (Dwarf_Debug dbg, Dwarf_Handler errhand);

/* Set new error handler argument.  */
extern Dwarf_Ptr dwarf_seterrarg (Dwarf_Debug dbg, Dwarf_Ptr errarg);

#endif	/* libdwarf.h */