dbgmod.h revision 3a4a6501d0ccd629d9951b644d380c7bb2d46086
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * IPRT - Internal Header for RTDbgMod and the associated interpreters.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Copyright (C) 2008-2009 Sun Microsystems, Inc.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * available from http://www.virtualbox.org. This file is free software;
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * you can redistribute it and/or modify it under the terms of the GNU
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * General Public License (GPL) as published by the Free Software
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * additional information or have any questions.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interperter
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @ingroup grp_rt
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @internal
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync/** Pointer to the internal module structure. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Virtual method table for executable image interpreters.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Magic number (RTDBGMODVTIMG_MAGIC). */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Mask of supported executable image types, see grp_rt_exe_img_type.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Used to speed up the search for a suitable interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The name of the interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync const char *pszName;
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Try open the image.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This combines probing and opening.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code. No informational returns defined.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module that is being opened.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The RTDBGMOD::pszDbgFile member will point to
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * the filename of any debug info we're aware of
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * on input. Also, or alternatively, it is expected
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * that the interpreter will look for debug info in
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * the executable image file when present and that it
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * may ask the image interpreter for this when it's
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Upon successful return the method is expected to
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * initialize pDbgOps and pvDbgPriv.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Close the interpreter, freeing all associated resources.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * to NULL upon return.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync/** Pointer to a const RTDBGMODVTIMG. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Virtual method table for debug info interpreters.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Magic number (RTDBGMODVTDBG_MAGIC). */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Mask of supported debug info types, see grp_rt_dbg_type.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Used to speed up the search for a suitable interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The name of the interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync const char *pszName;
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Try open the image.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This combines probing and opening.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code. No informational returns defined.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module that is being opened.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The RTDBGMOD::pszDbgFile member will point to
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * the filename of any debug info we're aware of
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * on input. Also, or alternatively, it is expected
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * that the interpreter will look for debug info in
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * the executable image file when present and that it
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * may ask the image interpreter for this when it's
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Upon successful return the method is expected to
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * initialize pDbgOps and pvDbgPriv.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Close the interpreter, freeing all associated resources.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * to NULL upon return.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Queries symbol information by symbol name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VINF_SUCCESS on success, no informational status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_RTDBGMOD_NO_SYMBOLS if there aren't any symbols.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszSymbol The symbol name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @para pSymbol Where to store the symbol information.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnSymbolByName)(PRTDBGMODINT pMod, const char *pszSymbol, PRTDBGSYMBOL pSymbol);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Queries symbol information by address.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * The returned symbol is what the debug info interpreter consideres the symbol
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * most applicable to the specified address. This usually means a symbol with an
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * address equal or lower than the requested.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VINF_SUCCESS on success, no informational status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_RTDBGMOD_NO_SYMBOLS if there aren't any symbols.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param off The offset into the segment.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param poffDisp Where to store the distance between the specified address
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * and the returned symbol. Optional.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pSymbol Where to store the symbol information.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTGCUINTPTR off, PRTGCINTPTR poffDisp, PRTDBGSYMBOL pSymbol);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Queries line number information by address.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VINF_SUCCESS on success, no informational status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_RTDBGMOD_NO_LINE_NUMBERS if there aren't any line numbers.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_RTDBGMOD_LINE_NOT_FOUND if no suitable line number was found.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param off The offset into the segment.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param poffDisp Where to store the distance between the specified address
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * and the returned line number. Optional.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pLine Where to store the information about the closest line number.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTGCUINTPTR off, PRTGCINTPTR poffDisp, PRTDBGLINE pLine);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Adds a symbol to the module (optional).
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This method is used to implement DBGFR3SymbolAdd.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @returns VBox status code.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pMod Pointer to the module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param pszSymbol The symbol name.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param off The offset into the segment.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * @param cbSymbol The area covered by the symbol. 0 is fine.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync DECLCALLBACKMEMBER(int, pfnSymbolAdd)(PRTDBGMODINT pMod, const char *pszSymbol, uint32_t iSeg, RTGCUINTPTR off, RTUINT cbSymbol);
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync/** Pointer to a const RTDBGMODVTDBG. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * Debug module structure.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsynctypedef struct RTDBGMOD
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Magic value (RTDBGMOD_MAGIC). */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The number of address spaces this module is currently linked into.
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync * This is used to perform automatic cleanup and sharing. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The module name (short). */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync const char *pszName;
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The module filename. Can be NULL. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The debug info file (if external). Can be NULL. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The method table for the executable image interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Pointer to the private data of the executable image interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** The method table for the debug info interpreter. */
3a4a6501d0ccd629d9951b644d380c7bb2d46086vboxsync /** Pointer to the private data of the debug info interpreter. */