/* Copyright (C) 2007-2010 The Android Open Source Project
**
** This software is licensed under the terms of the GNU General Public
** License version 2, as published by the Free Software Foundation, and
** may be copied, distributed, and modified under those terms.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
*/

/*
 * Contains declaration of types, strctures, routines, etc. that encapsulte
 * an API for parsing an ELF file containing debugging information in DWARF
 * format.
 */

#ifndef ELFF_API_H_
#define ELFF_API_H_

#ifdef __cplusplus
extern "C" {
#endif

#include <stdint.h>

/* Defines type for a handle used in ELFF API. */
typedef void* ELFF_HANDLE;

/* Defines an entry for 'inline_stack' array in Elf_AddressInfo structure.
 * Each entry in the array represents a routine, where routine represented
 * with the previous array entry has been inlined. First element in the array
 * (at index 0) represents information for the inlined routine, referenced by
 * Elf_AddressInfo structure itself. If name for a routine was not available
 * (DW_AT_name attribute was missing), routine name is set to "<unknown>".
 * Last entry in the array has all its fields set to zero. It's sufficient
 * just to check for routine_name field of this structure to be NULL to detect
 * last entry in the array.
 */
typedef struct Elf_InlineInfo {
  /* Name of the routine where previous routine is inlined.
   * This field can never be NULL, except for the last array entry.
   */
  const char*     routine_name;

  /* Source file name where routine is inlined.
   * This field can be NULL, if it was not possible to obtain information
   * about source file location for the routine. If this field is NULL, content
   * of inlined_in_file_dir and inlined_at_line fields is undefined and should
   * be ignored. */
  const char*     inlined_in_file;

  /* Source file directory where routine is inlined.
   * If inlined_in_file field contains NULL, content of this field is undefined
   * and should be ignored. */
  const char*     inlined_in_file_dir;

  /* Source file line number where routine is inlined.
   * If inlined_in_file field contains NULL, content of this field is undefined
   * and should be ignored. */
  uint32_t        inlined_at_line;
} Elf_InlineInfo;

/* Checks if an entry is the last entry in the array.
 * Return:
 *  Boolean: 1 if this is last entry, or zero otherwise.
 */
static inline int
elfinlineinfo_is_last_entry(const Elf_InlineInfo* info) {
    return info->routine_name == 0;
}

/* PC address information descriptor.
 * This descriptor contains as much information about a PC address as it was
 * possible to collect from an ELF file. */
typedef struct Elf_AddressInfo {
  /* Name of the routine containing the address. If name of the routine
   * was not available (DW_AT_name attribute was missing) this field
   * is set to "<unknown>". */
  const char*       routine_name;

  /* Name of the source file containing the routine. If source location for the
   * routine was not available, this field is set to NULL, and content of
   * dir_name, and line_number fields of this structure is not defined. */
  const char*       file_name;

  /* Path to the source file directory. If file_name field of this structure is
   * NULL, content of this field is not defined. */
  const char*       dir_name;

  /* Line number in the source file for the address. If file_name field of this
   * structure is NULL, content of this field is not defined. */
  uint32_t          line_number;

  /* If routine that contains the given address has been inlined (or it is part
   * of even deeper inline branch) this array lists information about that
   * inline branch rooting to the first routine that has not been inlined. The
   * first element in the array references a routine, where routine containing
   * the given address has been inlined. The second entry contains information
   * about a routine referenced by the first entry (and so on). If routine,
   * containing the given address has not been inlined, this field is set to
   * NULL. The array ends with an entry containing all zeroes. */
  Elf_InlineInfo*   inline_stack;
} Elf_AddressInfo;

//=============================================================================
// API routines
//=============================================================================

/* Initializes ELFF API for the given ELF file.
 * Param:
 *  elf_file_path - Path to the ELF file to initialize API for.
 * Return:
 *  On success, this routine returns a handle that can be used in subsequent
 *  calls to this API dealing with the given ELF file. On failure this routine
 *  returns NULL, with errno providing extended error information.
 *  NOTE: handle returned from this routine must be closed using elff_close().
 */
ELFF_HANDLE elff_init(const char* elf_file_path);

/* Closes a handle obtained after successful call to elff_init routine.
 * Param:
 *  handle - A handle to close. This handle must be a handle returned from
 *  a successful call to elff_init routine.
 */
void elff_close(ELFF_HANDLE handle);

/* Checks if ELF file represents an executable file, or a shared library.
 *  handle - A handle obtained from successful call to elff_init().
 * Return:
 *  1  if ELF file represents an executable file, or
 *  0  if ELF file represents a shared library, or
 *  -1 if handle is invalid.
 */
int elff_is_exec(ELFF_HANDLE handle);

/* Gets PC address information.
 * Param:
 *  handle - A handle obtained from successful call to elff_init().
 *  address - PC address to get information for. Address must be relative to
 *    the beginning of ELF file represented by the handle parameter.
 *  address_info - Upon success contains information about routine(s) that
 *    contain the given address.
 * Return:
 *  0 if routine(s) containing the given address has been found and information
 *  has been saved into address_info, or -1 if no appropriate routine for that
 *  address has been found, or there was a memory error when collecting
 *  routine(s) information. In case of failure, errno provides extended
 *  error information.
 *  NOTE: Successful call to this routine must be complimented with a call
 *  to free_pc_address_info, so ELFF API can release resources aquired for
 *  address_info.
 */
int elff_get_pc_address_info(ELFF_HANDLE handle,
                             uint64_t address,
                             Elf_AddressInfo* address_info);

/* Frees resources acquired for address information in successful call to
 * get_pc_address_info().
 * Param:
 *  handle - A handle obtained from successful call to elff_init().
 *  address_info - Address information structure, initialized in successful
 *    call to get_pc_address_info() routine.
 */
void elff_free_pc_address_info(ELFF_HANDLE handle,
                               Elf_AddressInfo* address_info);

#ifdef __cplusplus
}   /* end of extern "C" */
#endif

#endif  // ELFF_API_H_