source: trunk/kDbg/kDbg.h@ 3535

/* $Id: kDbg.h 3530 2007-08-20 03:42:03Z bird $ */
/** @file
 * kDbg - The Debug Info Reader.
 */

/*
 * Copyright (c) 2006-2007 knut st. osmundsen <bird-src-spam@anduin.net>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * 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.
 *
 * You should have received a copy of the GNU General Public License
 * along with This program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

#ifndef ___kDbg_h___
#define ___kDbg_h___

#include "kDbgBase.h"

#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup grp_kDbg      Debug Info Reader
 * @{
 */

/** The max filename path length used by the debug reader. */
#define KDBG_PATH_MAX       260

/** The max symbol name length used by the debug reader. */
#define KDBG_SYMBOL_MAX     384

/** @name   kDbg Status codes
 * (Success is indicated by the value 0.)
 * @{ */
#define KDBG_ERR_BASE                                   430000

/** An API was given an invalid parameter. */
#define KDBG_ERR_INVALID_PARAMETER                      (KDBG_ERR_BASE + 0)
/** A pointer argument is not valid. */
#define KDBG_ERR_INVALID_POINTER                        (KDBG_ERR_BASE + 1)
/** A handle argument is not valid. */
#define KDBG_ERR_INVALID_HANDLE                         (KDBG_ERR_BASE + 2)
/** A parameter is out of range. */
#define KDBG_ERR_OUT_OF_RANGE                           (KDBG_ERR_BASE + 3)
/** Out of memory. */
#define KDBG_ERR_NO_MEMORY                              (KDBG_ERR_BASE + 4)
/** The specified file was not found. */
#define KDBG_ERR_FILE_NOT_FOUND                         (KDBG_ERR_BASE + 5)
/** Hit some unimplemented functionality - feel free to implement it :-) . */
#define KDBG_ERR_NOT_IMPLEMENTED                        (KDBG_ERR_BASE + 6)
/** Generic error. */
#define KDBG_ERR_GENERAL_FAILURE                        (KDBG_ERR_BASE + 9)

/** The (module) format isn't known to use. */
#define KDBG_ERR_UNKOWN_FORMAT                          (KDBG_ERR_BASE + 10)
/** The (module) format isn't supported by this kDbg build. */
#define KDBG_ERR_FORMAT_NOT_SUPPORTED                   (KDBG_ERR_BASE + 11)
/** A specified address or an address found in the debug info is invalid. */
#define KDBG_ERR_INVALID_ADDRESS                        (KDBG_ERR_BASE + 12)
/** The dbghelp.dll is too old or something like that. */
#define KDBG_ERR_DBGHLP_VERSION_MISMATCH                (KDBG_ERR_BASE + 13)
/** Invalid executable format. */
#define KDBG_ERR_BAD_EXE_FORMAT                         (KDBG_ERR_BASE + 14)

/** @} */


/** @name   Special Segments
 * @{ */
/** Relative Virtual Address.
 * The specified offset is relative to the image base. The image base is the lowest memory
 * address used by the image when loaded with the address assignments indicated in the image. */
#define KDBGSEG_RVA (-1)
/** Absolute segment. The offset isn't relative to anything. */
#define KDBGSEG_ABS (-2)
/** @} */


/**
 * Line number details.
 */
typedef struct KDBGLINE
{
    /** The relative virtual address. */
    KDBGADDR    RVA;
    /** The offset into the segment. */
    KDBGADDR    offSegment;
    /** The segment number. */
    int32_t     iSegment;
    /** The Line number. */
    uint32_t    iLine;
    /** The length of the filename. */
    uint16_t    cchFile;
    /** The name of the file this line number relates to. */
    char        szFile[KDBG_PATH_MAX];
} KDBGLINE;
/** Pointer to line number details. */
typedef KDBGLINE *PKDBGLINE;
/** Pointer to const line number details. */
typedef const KDBGLINE *PCKDBGLINE;
/** Pointer to a pointer to line number details. */
typedef PKDBGLINE *PPKDBGLINE;

/**
 * Duplicates a line number.
 *
 * To save heap space, the returned line number will not own more heap space
 * than it strictly need to. So, it's not possible to append stuff to the symbol
 * or anything of that kind.
 *
 * @returns Pointer to the duplicate.
 *          This must be freed using RTDbgSymbolFree().
 * @param   pLine       The line number to be duplicated.
 */
KDBG_DECL(PKDBGLINE) kDbgLineDup(PCKDBGLINE pLine);

/**
 * Frees a line number obtained from the RTDbg API.
 *
 * @returns VINF_SUCCESS on success.
 * @returns KDBG_ERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
 *
 * @param   pLine       The line number to be freed.
 */
KDBG_DECL(int) kDbgLineFree(PKDBGLINE pLine);


/** @name Symbol Flags.
 * @{ */
/** The symbol is weak. */
#define KDBGSYM_FLAGS_WEAK      UINT32_C(0x00000000)
/** The symbol is absolute.
 * (This also indicated by the segment number.) */
#define KDBGSYM_FLAGS_ABS       UINT32_C(0x00000001)
/** The symbol is exported. */
#define KDBGSYM_FLAGS_EXPORTED  UINT32_C(0x00000002)
/** The symbol is a function/method/procedure/whatever-executable-code. */
#define KDBGSYM_FLAGS_CODE      UINT32_C(0x00000004)
/** The symbol is some kind of data. */
#define KDBGSYM_FLAGS_DATA      UINT32_C(0x00000008)
/** @} */

/**
 * Symbol details.
 */
typedef struct KDBGSYMBOL
{
    /** The relative virtual address. */
    KDBGADDR    RVA;
    /** The symbol size.
     * This is not a reliable field, it could be a bad guess. Ignore if zero. */
    KDBGADDR    cb;
    /** The offset into the segment. */
    KDBGADDR    offSegment;
    /** The segment number. */
    int32_t     iSegment;
    /** The symbol flags. */
    uint32_t    fFlags;
/** @todo type info? */
    /** The length of the symbol name. */
    uint16_t    cchName;
    /** The symbol name. */
    char        szName[KDBG_SYMBOL_MAX];
} KDBGSYMBOL;
/** Pointer to symbol details. */
typedef KDBGSYMBOL *PKDBGSYMBOL;
/** Pointer to const symbol details. */
typedef const KDBGSYMBOL *PCKDBGSYMBOL;
/** Pointer to a pointer to symbol details. */
typedef PKDBGSYMBOL *PPKDBGSYMBOL;

/**
 * Duplicates a symbol.
 *
 * To save heap space, the returned symbol will not own more heap space than
 * it strictly need to. So, it's not possible to append stuff to the symbol
 * or anything of that kind.
 *
 * @returns Pointer to the duplicate.
 *          This must be freed using kDbgSymbolFree().
 * @param   pSymbol     The symbol to be freed.
 */
KDBG_DECL(PKDBGSYMBOL) kDbgSymbolDup(PCKDBGSYMBOL pSymbol);

/**
 * Frees a symbol obtained from the kDbg API.
 *
 * @returns VINF_SUCCESS on success.
 * @returns KDBG_ERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
 *
 * @param   pSymbol     The symbol to be freed.
 */
KDBG_DECL(int) kDbgSymbolFree(PKDBGSYMBOL pSymbol);



/** A debug module handle. */
typedef struct KDBGMOD *PKDBGMOD;

/**
 * Opens the debug info for a specified executable module.
 *
 * @returns IPRT status code.
 * @param   pszModulePath       The path to the executable module.
 * @param   ppDbgMod            Where to store the debug module handle.
 */
KDBG_DECL(int) kDbgModuleOpen(const char *pszModulePath, PKDBGMOD *ppDbgMod);

/**
 * Closes the module.
 *
 * @returns IPRT status code.
 * @param   pMod        The module handle.
 */
KDBG_DECL(int) kDbgModuleClose(PKDBGMOD pMod);

/**
 * Gets a symbol by segment:offset.
 * This will be approximated to the nearest symbol if there is no exact match.
 *
 * @returns IPRT status code.
 * @param   pMod        The module.
 * @param   iSegment    The segment this offset is relative to.
 *                      The -1 segment is special, it means that the addres is relative to
 *                      the image base. The image base is where the first bit of the image
 *                      is mapped during load.
 * @param   off         The offset into the segment.
 * @param   pSym        Where to store the symbol details.
 */
KDBG_DECL(int) kDbgModuleQuerySymbol(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PKDBGSYMBOL pSym);

/**
 * Gets & allocates a symbol by segment:offset.
 * This will be approximated to the nearest symbol if there is no exact match.
 *
 * @returns IPRT status code.
 * @param   pMod        The module.
 * @param   iSegment    The segment this offset is relative to.
 *                      The -1 segment is special, it means that the addres is relative to
 *                      the image base. The image base is where the first bit of the image
 *                      is mapped during load.
 * @param   off         The offset into the segment.
 * @param   ppSym       Where to store the pointer to the symbol info.
 *                      Free the returned symbol using kDbgSymbolFree().
 */
KDBG_DECL(int) kDbgModuleQuerySymbolA(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PPKDBGSYMBOL ppSym);

/**
 * Gets a line number entry by segment:offset.
 * This will be approximated to the nearest line number there is no exact match.
 *
 * @returns IPRT status code.
 * @param   pMod        The module.
 * @param   iSegment    The segment this offset is relative to.
 *                      The -1 segment is special, it means that the addres is relative to
 *                      the image base. The image base is where the first bit of the image
 *                      is mapped during load.
 * @param   off         The offset into the segment.
 * @param   pLine       Where to store the line number details.
 */
KDBG_DECL(int) kDbgModuleQueryLine(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PKDBGLINE pLine);

/**
 * Gets & allocates a line number entry by segment:offset.
 * This will be approximated to the nearest line number there is no exact match.
 *
 * @returns IPRT status code.
 * @param   pMod        The module.
 * @param   iSegment    The segment this offset is relative to.
 *                      The -1 segment is special, it means that the addres is relative to
 *                      the image base. The image base is where the first bit of the image
 *                      is mapped during load.
 * @param   off         The offset into the segment.
 * @param   ppLine      Where to store the pointer to the line number info.
 *                      Free the returned line number using kDbgLineFree().
 */
KDBG_DECL(int) kDbgModuleQueryLineA(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PPKDBGLINE ppLine);


/** @} */

#ifdef __cplusplus
}
#endif

#endif