dbgmod.h revision 2bb12e589d2c280ad042e4e70635ae7224c7ecee
/* $Id$ */
/** @file
* IPRT - Internal Header for RTDbgMod and the associated interpreters.
*/
/*
* Copyright (C) 2008-2009 Sun Microsystems, Inc.
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*
* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
* Clara, CA 95054 USA or visit http://www.sun.com if you need
* additional information or have any questions.
*/
#ifndef ___internal_dbgmod_h
#define ___internal_dbgmod_h
#include <iprt/critsect.h>
/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interperter
* @ingroup grp_rt
* @internal
* @{
*/
/** Pointer to the internal module structure. */
typedef struct RTDBGMODINT *PRTDBGMODINT;
/**
* Virtual method table for executable image interpreters.
*/
typedef struct RTDBGMODVTIMG
{
/** Magic number (RTDBGMODVTIMG_MAGIC). */
/** Mask of supported executable image types, see grp_rt_exe_img_type.
* Used to speed up the search for a suitable interpreter. */
/** The name of the interpreter. */
const char *pszName;
/**
* Try open the image.
*
* This combines probing and opening.
*
* @returns IPRT status code. No informational returns defined.
*
* @param pMod Pointer to the module that is being opened.
*
* The RTDBGMOD::pszDbgFile member will point to
* the filename of any debug info we're aware of
* on input. Also, or alternatively, it is expected
* that the interpreter will look for debug info in
* the executable image file when present and that it
* may ask the image interpreter for this when it's
* around.
*
* Upon successful return the method is expected to
* initialize pDbgOps and pvDbgPriv.
*/
/**
* Close the interpreter, freeing all associated resources.
*
* The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
* to NULL upon return.
*
* @param pMod Pointer to the module structure.
*/
/** Pointer to a const RTDBGMODVTIMG. */
typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
/**
* Virtual method table for debug info interpreters.
*/
typedef struct RTDBGMODVTDBG
{
/** Magic number (RTDBGMODVTDBG_MAGIC). */
/** Mask of supported debug info types, see grp_rt_dbg_type.
* Used to speed up the search for a suitable interpreter. */
/** The name of the interpreter. */
const char *pszName;
/**
* Try open the image.
*
* This combines probing and opening.
*
* @returns IPRT status code. No informational returns defined.
*
* @param pMod Pointer to the module that is being opened.
*
* The RTDBGMOD::pszDbgFile member will point to
* the filename of any debug info we're aware of
* on input. Also, or alternatively, it is expected
* that the interpreter will look for debug info in
* the executable image file when present and that it
* may ask the image interpreter for this when it's
* around.
*
* Upon successful return the method is expected to
* initialize pDbgOps and pvDbgPriv.
*/
/**
* Close the interpreter, freeing all associated resources.
*
* The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
* to NULL upon return.
*
* @param pMod Pointer to the module structure.
*/
/**
* Converts an image relative virtual address address to a segmented address.
*
* @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
* @param pMod Pointer to the module structure.
* @param uRva The image relative address to convert.
* @param poffSeg Where to return the segment offset. Optional.
*/
DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff)(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
/**
* Image size when mapped if segments are mapped adjecently.
*
* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
* NE and such it's a bit odder and the answer may not make much sense for them.
*
* @returns Image mapped size.
* @param pMod Pointer to the module structure.
*/
/**
* Adds a segment to the module (optional).
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
* @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
*
* @param pMod Pointer to the module structure.
* @param uRva The segment image relative address.
* @param cb The segment size.
* @param pszName The segment name.
* @param cchName The length of the segment name.
* @param fFlags Segment flags.
* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
* The assigned segment index on successful return.
* Optional.
*/
DECLCALLBACKMEMBER(int, pfnSegmentAdd)(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
/**
* Gets the segment count.
*
* @returns Number of segments.
* @retval NIL_RTDBGSEGIDX if unknown.
*
* @param pMod Pointer to the module structure.
*/
/**
* Gets information about a segment.
*
* @returns IPRT status code.
* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
*
* @param pMod Pointer to the module structure.
* @param iSeg The segment.
* @param pSegInfo Where to store the segment information.
*/
DECLCALLBACKMEMBER(int, pfnSegmentByIndex)(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
/**
* Adds a symbol to the module (optional).
*
* @returns IPRT code.
* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
*
* @param pMod Pointer to the module structure.
* @param pszSymbol The symbol name.
* @param cchSymbol The length for the symbol name.
* @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
* @param off The offset into the segment.
* @param cb The area covered by the symbol. 0 is fine.
* @param piOrdinal Where to return the symbol ordinal on success. If the
* interpreter doesn't do ordinals, this will be set to
* UINT32_MAX. Optional
*/
/**
* Gets the number of symbols in the module.
*
* This is used for figuring out the max value to pass to pfnSymbolByIndex among
* other things.
*
*
* @param pMod Pointer to the module structure.
*/
/**
* Queries symbol information by ordinal number.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS on success, no informational status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
*
* @param pMod Pointer to the module structure.
* @param iSymbol The symbol ordinal number.
* @param pSymbol Where to store the symbol information.
*/
DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal)(PRTDBGMODINT pMod, uint32_t iSymbol, PRTDBGSYMBOL pSymbol);
/**
* Queries symbol information by symbol name.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS on success, no informational status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
*
* @param pMod Pointer to the module structure.
* @param pszSymbol The symbol name.
* @para pSymbol Where to store the symbol information.
*/
DECLCALLBACKMEMBER(int, pfnSymbolByName)(PRTDBGMODINT pMod, const char *pszSymbol, PRTDBGSYMBOL pSymbol);
/**
* Queries symbol information by address.
*
* The returned symbol is what the debug info interpreter consideres the symbol
* most applicable to the specified address. This usually means a symbol with an
* address equal or lower than the requested.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS on success, no informational status code.
* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
*
* @param pMod Pointer to the module structure.
* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the specified address
* and the returned symbol. Optional.
* @param pSymbol Where to store the symbol information.
*/
DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol);
/**
* Adds a line number to the module (optional).
*
* @returns IPRT status code.
* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
*
* @param pMod Pointer to the module structure.
* @param pszFile The filename.
* @param cchFile The length of the filename.
* @param iSeg The segment number (0-based).
* @param off The offset into the segment.
* @param piOrdinal Where to return the line number ordinal on success. If
* the interpreter doesn't do ordinals, this will be set to
* UINT32_MAX. Optional
*/
DECLCALLBACKMEMBER(int, pfnLineAdd)(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
/**
* Gets the number of line numbers in the module.
*
*
* @param pMod Pointer to the module structure.
*/
/**
* Queries line number information by ordinal number.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS on success, no informational status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
* ordinal.
*
* @param pMod Pointer to the module structure.
* @param iOrdinal The line number ordinal number.
* @param pLine Where to store the information about the line number.
*/
/**
* Queries line number information by address.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS on success, no informational status code.
* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
*
* @param pMod Pointer to the module structure.
* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
* @param off The offset into the segment.
* @param poffDisp Where to store the distance between the specified address
* and the returned line number. Optional.
* @param pLine Where to store the information about the closest line number.
*/
DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLine);
/** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
/** Pointer to a const RTDBGMODVTDBG. */
typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
/**
* Debug module structure.
*/
typedef struct RTDBGMODINT
{
/** Magic value (RTDBGMOD_MAGIC). */
/** The number of reference there are to this module.
* This is used to perform automatic cleanup and sharing. */
/** The module name (short). */
char *pszName;
/** The module filename. Can be NULL. */
char *pszImgFile;
/** The debug info file (if external). Can be NULL. */
char *pszDbgFile;
/** Critical section serializing access to the module. */
/** The method table for the executable image interpreter. */
/** Pointer to the private data of the executable image interpreter. */
void *pvImgPriv;
/** The method table for the debug info interpreter. */
/** Pointer to the private data of the debug info interpreter. */
void *pvDbgPriv;
} RTDBGMODINT;
/** Pointer to an debug module structure. */
typedef RTDBGMODINT *PRTDBGMODINT;
/** @} */
#endif