source: trunk/kProfile/dbg.h@ 3524

/* $Id: $ */
/** @file
 *
 * kProfile Mark 2 - Debug Info Reader.
 *
 * Copyright (c) 2006 knut st. osmundsen <bird-src-spam@anduin.net.de>
 *
 *
 * 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 __iprt_dbg_h__
#define __iprt_dbg_h__

#include <iprt/types.h>

__BEGIN_DECLS

/** @defgroup grp_rt_dbg    Debug Info Reader
 * @addtogroup grp_rt
 * @{
 */

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

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


/** @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 RTDBGSEG_RVA (-1)
/** Absolute segment. The offset isn't relative to anything. */
#define RTDBGSEG_ABS (-2)
/** @} */


/**
 * Line number details.
 */
typedef struct RTDBGLINE
{
    /** The relative virtual address. */
    RTUINTPTR   RVA;
    /** The offset into the segment. */
    RTUINTPTR   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[RTDBG_PATH_MAX];
} RTDBGLINE;
/** Pointer to line number details. */
typedef RTDBGLINE *PRTDBGLINE;
/** Pointer to const line number details. */
typedef const RTDBGLINE *PCRTDBGLINE;
/** Pointer to a pointer to line number details. */
typedef PRTDBGLINE *PPRTDBGLINE;

/**
 * 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.
 */
RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);

/**
 * Frees a line number obtained from the RTDbg API.
 *
 * @returns VINF_SUCCESS on success.
 * @returns VERR_INVALID_POINTER if a NULL pointer or an !VALID_PTR() is passed in.
 *
 * @param   pLine       The line number to be freed.
 */
RTDECL(int) RTDbgLineFree(PRTDBGLINE pLine);


/** @name Symbol Flags.
 * @{ */
/** The symbol is weak. */
#define RTDBGSYM_FLAGS_WEAK     BIT(0)
/** The symbol is absolute.
 * (This also indicated by the segment number.) */
#define RTDBGSYM_FLAGS_ABS      BIT(1)
/** The symbol is exported. */
#define RTDBGSYM_FLAGS_EXPORTED BIT(2)
/** The symbol is a function/method/procedure/whatever-executable-code. */
#define RTDBGSYM_FLAGS_CODE     BIT(3)
/** The symbol is some kind of data. */
#define RTDBGSYM_FLAGS_DATA     BIT(4)
/** @} */

/**
 * Symbol details.
 */
typedef struct RTDBGSYMBOL
{
    /** The relative virtual address. */
    RTUINTPTR   RVA;
    /** The symbol size.
     * This is not a reliable field, it could be a bad guess. Ignore if zero. */
    RTUINTPTR   cb;
    /** The offset into the segment. */
    RTUINTPTR   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[RTDBG_SYMBOL_MAX];
} RTDBGSYMBOL;
/** Pointer to symbol details. */
typedef RTDBGSYMBOL *PRTDBGSYMBOL;
/** Pointer to const symbol details. */
typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
/** Pointer to a pointer to symbol details. */
typedef PRTDBGSYMBOL *PPRTDBGSYMBOL;


/**
 * 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 RTDbgSymbolFree().
 * @param   pSymbol     The symbol to be freed.
 */
RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymbol);

/**
 * Frees a symbol obtained from the RTDbg API.
 *
 * @returns VINF_SUCCESS on success.
 * @returns VERR_INVALID_POINTER if a NULL pointer or an !VALID_PTR() is passed in.
 *
 * @param   pSymbol     The symbol to be freed.
 */
RTDECL(int) RTDbgSymbolFree(PRTDBGSYMBOL pSymbol);



/** A debug module handle. */
typedef struct RTDBGMOD *PRTDBGMOD;

/**
 * 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.
 */
RTDECL(int) RTDbgModuleOpen(const char *pszModulePath, PRTDBGMOD *ppDbgMod);

/**
 * Closes the module.
 *
 * @returns IPRT status code.
 * @param   pMod        The module handle.
 */
RTDECL(int) RTDbgModuleClose(PRTDBGMOD 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.
 */
RTDECL(int) RTDbgModuleQuerySymbol(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PRTDBGSYMBOL 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 RTDbgSymbolFree().
 */
RTDECL(int) RTDbgModuleQuerySymbolA(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PPRTDBGSYMBOL 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.
 */
RTDECL(int) RTDbgModuleQueryLine(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PRTDBGLINE 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 RTDbgLineFree().
 */
RTDECL(int) RTDbgModuleQueryLineA(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PPRTDBGLINE ppLine);


__END_DECLS

/** @} */

#endif