/** @file * Debugger Interfaces. (VBoxDbg) * * This header covers all external interfaces of the Debugger module. * However, it does not cover the DBGF interface since that part of the * VMM. Use dbgf.h for that. */ /* * Copyright (C) 2006-2007 Oracle Corporation * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * 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. */ #ifndef ___VBox_dbg_h #define ___VBox_dbg_h #include #include #include #include #ifdef IN_RING3 # include #endif RT_C_DECLS_BEGIN #ifdef IN_RING3 /* The debugger stuff is ring-3 only. */ /** @def VBOX_WITH_DEBUGGER * The build is with debugger module. Test if this is defined before registering * external debugger commands. This is normally defined in Config.kmk. */ #ifdef DOXYGEN_RUNNING # define VBOX_WITH_DEBUGGER #endif /** * DBGC variable category. * * Used to describe an argument to a command or function and a functions * return value. */ typedef enum DBGCVARCAT { /** Any type is fine. */ DBGCVAR_CAT_ANY = 0, /** Any kind of pointer or number. */ DBGCVAR_CAT_POINTER_NUMBER, /** Any kind of pointer or number, no range. */ DBGCVAR_CAT_POINTER_NUMBER_NO_RANGE, /** Any kind of pointer. */ DBGCVAR_CAT_POINTER, /** Any kind of pointer with no range option. */ DBGCVAR_CAT_POINTER_NO_RANGE, /** GC pointer. */ DBGCVAR_CAT_GC_POINTER, /** GC pointer with no range option. */ DBGCVAR_CAT_GC_POINTER_NO_RANGE, /** Numeric argument. */ DBGCVAR_CAT_NUMBER, /** Numeric argument with no range option. */ DBGCVAR_CAT_NUMBER_NO_RANGE, /** String. */ DBGCVAR_CAT_STRING, /** Symbol. */ DBGCVAR_CAT_SYMBOL, /** Option. */ DBGCVAR_CAT_OPTION, /** Option + string. */ DBGCVAR_CAT_OPTION_STRING, /** Option + number. */ DBGCVAR_CAT_OPTION_NUMBER } DBGCVARCAT; /** * DBGC variable type. */ typedef enum DBGCVARTYPE { /** unknown... */ DBGCVAR_TYPE_UNKNOWN = 0, /** Flat GC pointer. */ DBGCVAR_TYPE_GC_FLAT, /** Segmented GC pointer. */ DBGCVAR_TYPE_GC_FAR, /** Physical GC pointer. */ DBGCVAR_TYPE_GC_PHYS, /** Flat HC pointer. */ DBGCVAR_TYPE_HC_FLAT, /** Physical HC pointer. */ DBGCVAR_TYPE_HC_PHYS, /** Number. */ DBGCVAR_TYPE_NUMBER, /** String. */ DBGCVAR_TYPE_STRING, /** Symbol. */ DBGCVAR_TYPE_SYMBOL, /** Special type used when querying symbols. */ DBGCVAR_TYPE_ANY } DBGCVARTYPE; /** @todo Rename to DBGCVAR_IS_xyz. */ /** Checks if the specified variable type is of a pointer persuasion. */ #define DBGCVAR_ISPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS) /** Checks if the specified variable type is of a pointer persuasion. */ #define DBGCVAR_IS_FAR_PTR(enmType) ((enmType) == DBGCVAR_TYPE_GC_FAR) /** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */ #define DBGCVAR_ISGCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_GC_FLAT && (enmType) <= DBGCVAR_TYPE_GC_PHYS) /** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */ #define DBGCVAR_ISHCPOINTER(enmType) ((enmType) >= DBGCVAR_TYPE_HC_FLAT && (enmType) <= DBGCVAR_TYPE_HC_PHYS) /** * DBGC variable range type. */ typedef enum DBGCVARRANGETYPE { /** No range appliable or no range specified. */ DBGCVAR_RANGE_NONE = 0, /** Number of elements. */ DBGCVAR_RANGE_ELEMENTS, /** Number of bytes. */ DBGCVAR_RANGE_BYTES } DBGCVARRANGETYPE; /** * Variable descriptor. */ typedef struct DBGCVARDESC { /** The minimal number of times this argument may occur. * Use 0 here to inidicate that the argument is optional. */ unsigned cTimesMin; /** Maximum number of occurrences. * Use ~0 here to indicate infinite. */ unsigned cTimesMax; /** Argument category. */ DBGCVARCAT enmCategory; /** Flags, DBGCVD_FLAGS_* */ unsigned fFlags; /** Argument name. */ const char *pszName; /** Argument name. */ const char *pszDescription; } DBGCVARDESC; /** Pointer to an argument descriptor. */ typedef DBGCVARDESC *PDBGCVARDESC; /** Pointer to a const argument descriptor. */ typedef const DBGCVARDESC *PCDBGCVARDESC; /** Variable descriptor flags. * @{ */ /** Indicates that the variable depends on the previous being present. */ #define DBGCVD_FLAGS_DEP_PREV RT_BIT(1) /** @} */ /** * DBGC variable. */ typedef struct DBGCVAR { /** Pointer to the argument descriptor. */ PCDBGCVARDESC pDesc; /** Pointer to the next argument. */ struct DBGCVAR *pNext; /** Argument type. */ DBGCVARTYPE enmType; /** Type specific. */ union { /** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */ RTGCPTR GCFlat; /** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */ RTFAR32 GCFar; /** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */ RTGCPHYS GCPhys; /** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */ void *pvHCFlat; /** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */ RTHCPHYS HCPhys; /** String. (DBGCVAR_TYPE_STRING) * The basic idea is the the this is a pointer to the expression we're * parsing, so no messing with freeing. */ const char *pszString; /** Number. (DBGCVAR_TYPE_NUMBER) */ uint64_t u64Number; } u; /** Range type. */ DBGCVARRANGETYPE enmRangeType; /** Range. The use of the content depends on the enmRangeType. */ uint64_t u64Range; } DBGCVAR; /** Pointer to a command argument. */ typedef DBGCVAR *PDBGCVAR; /** Pointer to a const command argument. */ typedef const DBGCVAR *PCDBGCVAR; /** * Macro for initializing a DBGC variable with defaults. * The result is an unknown variable type without any range. */ #define DBGCVAR_INIT(pVar) \ do { \ (pVar)->pDesc = NULL;\ (pVar)->pNext = NULL; \ (pVar)->enmType = DBGCVAR_TYPE_UNKNOWN; \ (pVar)->u.u64Number = 0; \ (pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \ (pVar)->u64Range = 0; \ } while (0) /** * Macro for initializing a DBGC variable with a HC physical address. */ #define DBGCVAR_INIT_HC_PHYS(pVar, Phys) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_HC_PHYS; \ (pVar)->u.HCPhys = (Phys); \ } while (0) /** * Macro for initializing a DBGC variable with a HC flat address. */ #define DBGCVAR_INIT_HC_FLAT(pVar, Flat) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_HC_FLAT; \ (pVar)->u.pvHCFlat = (Flat); \ } while (0) /** * Macro for initializing a DBGC variable with a GC physical address. */ #define DBGCVAR_INIT_GC_PHYS(pVar, Phys) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_GC_PHYS; \ (pVar)->u.GCPhys = (Phys); \ } while (0) /** * Macro for initializing a DBGC variable with a GC flat address. */ #define DBGCVAR_INIT_GC_FLAT(pVar, Flat) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \ (pVar)->u.GCFlat = (Flat); \ } while (0) /** * Macro for initializing a DBGC variable with a GC flat address. */ #define DBGCVAR_INIT_GC_FLAT_BYTE_RANGE(pVar, Flat, cbRange) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_GC_FLAT; \ (pVar)->u.GCFlat = (Flat); \ DBGCVAR_SET_RANGE(pVar, DBGCVAR_RANGE_BYTES, cbRange); \ } while (0) /** * Macro for initializing a DBGC variable with a GC far address. */ #define DBGCVAR_INIT_GC_FAR(pVar, _sel, _off) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_GC_FAR; \ (pVar)->u.GCFar.sel = (_sel); \ (pVar)->u.GCFar.off = (_off); \ } while (0) /** * Macro for initializing a DBGC variable with a number. */ #define DBGCVAR_INIT_NUMBER(pVar, Value) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_NUMBER; \ (pVar)->u.u64Number = (Value); \ } while (0) /** * Macro for initializing a DBGC variable with a string. */ #define DBGCVAR_INIT_STRING(pVar, a_pszString) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_STRING; \ (pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \ (pVar)->u.pszString = (a_pszString); \ (pVar)->u64Range = strlen(a_pszString); \ } while (0) /** * Macro for initializing a DBGC variable with a symbol. */ #define DBGCVAR_INIT_SYMBOL(pVar, a_pszSymbol) \ do { \ DBGCVAR_INIT(pVar); \ (pVar)->enmType = DBGCVAR_TYPE_SYMBOL; \ (pVar)->enmRangeType = DBGCVAR_RANGE_BYTES; \ (pVar)->u.pszString = (a_pszSymbol); \ (pVar)->u64Range = strlen(a_pszSymbol); \ } while (0) /** * Macro for setting the range of a DBGC variable. * @param pVar The variable. * @param _enmRangeType The range type. * @param Value The range length value. */ #define DBGCVAR_SET_RANGE(pVar, _enmRangeType, Value) \ do { \ (pVar)->enmRangeType = (_enmRangeType); \ (pVar)->u64Range = (Value); \ } while (0) /** * Macro for setting the range of a DBGC variable. * @param a_pVar The variable. * @param a_cbRange The range, in bytes. */ #define DBGCVAR_SET_BYTE_RANGE(a_pVar, a_cbRange) \ DBGCVAR_SET_RANGE(a_pVar, DBGCVAR_RANGE_BYTES, a_cbRange) /** * Macro for resetting the range a DBGC variable. * @param a_pVar The variable. */ #define DBGCVAR_ZAP_RANGE(a_pVar) \ do { \ (a_pVar)->enmRangeType = DBGCVAR_RANGE_NONE; \ (a_pVar)->u64Range = 0; \ } while (0) /** * Macro for assigning one DBGC variable to another. * @param a_pResult The result (target) variable. * @param a_pVar The source variable. */ #define DBGCVAR_ASSIGN(a_pResult, a_pVar) \ do { \ *(a_pResult) = *(a_pVar); \ } while (0) /** Pointer to a command descriptor. */ typedef struct DBGCCMD *PDBGCCMD; /** Pointer to a const command descriptor. */ typedef const struct DBGCCMD *PCDBGCCMD; /** Pointer to a function descriptor. */ typedef struct DBGCFUNC *PDBGCFUNC; /** Pointer to a const function descriptor. */ typedef const struct DBGCFUNC *PCDBGCFUNC; /** Pointer to helper functions for commands. */ typedef struct DBGCCMDHLP *PDBGCCMDHLP; /** * Helper functions for commands. */ typedef struct DBGCCMDHLP { /** Magic value (DBGCCMDHLP_MAGIC). */ uint32_t u32Magic; /** * Command helper for writing formatted text to the debug console. * * @returns VBox status. * @param pCmdHlp Pointer to the command callback structure. * @param pcb Where to store the number of bytes written. * @param pszFormat The format string. This may use all IPRT extensions as * well as the debugger ones. * @param ... Arguments specified in the format string. */ DECLCALLBACKMEMBER(int, pfnPrintf)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, ...); /** * Command helper for writing formatted text to the debug console. * * @returns VBox status. * @param pCmdHlp Pointer to the command callback structure. * @param pcb Where to store the number of bytes written. * @param pszFormat The format string. This may use all IPRT extensions as * well as the debugger ones. * @param args Arguments specified in the format string. */ DECLCALLBACKMEMBER(int, pfnPrintfV)(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, va_list args); /** * Command helper for formatting a string with debugger format specifiers. * * @returns The number of bytes written. * @param pCmdHlp Pointer to the command callback structure. * @param pszBuf The output buffer. * @param cbBuf The size of the output buffer. * @param pszFormat The format string. This may use all IPRT extensions as * well as the debugger ones. * @param ... Arguments specified in the format string. */ DECLCALLBACKMEMBER(size_t, pfnStrPrintf)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf, const char *pszFormat, ...); /** * Command helper for formatting a string with debugger format specifiers. * * @returns The number of bytes written. * @param pCmdHlp Pointer to the command callback structure. * @param pszBuf The output buffer. * @param cbBuf The size of the output buffer. * @param pszFormat The format string. This may use all IPRT extensions as * well as the debugger ones. * @param va Arguments specified in the format string. */ DECLCALLBACKMEMBER(size_t, pfnStrPrintfV)(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf, const char *pszFormat, va_list va); /** * Command helper for formatting and error message for a VBox status code. * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param rc The VBox status code. * @param pszFormat Format string for additional messages. Can be NULL. * @param ... Format arguments, optional. */ DECLCALLBACKMEMBER(int, pfnVBoxError)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...); /** * Command helper for formatting and error message for a VBox status code. * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param rc The VBox status code. * @param pcb Where to store the number of bytes written. * @param pszFormat Format string for additional messages. Can be NULL. * @param args Format arguments, optional. */ DECLCALLBACKMEMBER(int, pfnVBoxErrorV)(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args); /** * Command helper for reading memory specified by a DBGC variable. * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param pVM VM handle if GC or physical HC address. * @param pvBuffer Where to store the read data. * @param cbRead Number of bytes to read. * @param pVarPointer DBGC variable specifying where to start reading. * @param pcbRead Where to store the number of bytes actually read. * This optional, but it's useful when read GC virtual memory where a * page in the requested range might not be present. * If not specified not-present failure or end of a HC physical page * will cause failure. */ DECLCALLBACKMEMBER(int, pfnMemRead)(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead); /** * Command helper for writing memory specified by a DBGC variable. * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param pVM VM handle if GC or physical HC address. * @param pvBuffer What to write. * @param cbWrite Number of bytes to write. * @param pVarPointer DBGC variable specifying where to start reading. * @param pcbWritten Where to store the number of bytes written. * This is optional. If NULL be aware that some of the buffer * might have been written to the specified address. */ DECLCALLBACKMEMBER(int, pfnMemWrite)(PDBGCCMDHLP pCmdHlp, PVM pVM, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten); /** * Executes command an expression. * (Hopefully the parser and functions are fully reentrant.) * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param pszExpr The expression. Format string with the format DBGC extensions. * @param ... Format arguments. */ DECLCALLBACKMEMBER(int, pfnExec)(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...); /** * Evaluates an expression. * (Hopefully the parser and functions are fully reentrant.) * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param pResult Where to store the result. * @param pszExpr The expression. Format string with the format DBGC extensions. * @param va Format arguments. */ DECLCALLBACKMEMBER(int, pfnEvalV)(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, va_list va); /** * Print an error and fail the current command. * * @returns VBox status code to pass upwards. * * @param pCmdHlp Pointer to the command callback structure. * @param pCmd The failing command. * @param pszFormat The error message format string. * @param va Format arguments. */ DECLCALLBACKMEMBER(int, pfnFailV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, va_list va); /** * Print an error and fail the current command. * * @returns VBox status code to pass upwards. * * @param pCmdHlp Pointer to the command callback structure. * @param pCmd The failing command. * @param rc The status code indicating the failure. This will * be appended to the message after a colon (': '). * @param pszFormat The error message format string. * @param va Format arguments. * * @see DBGCCmdHlpFailRc */ DECLCALLBACKMEMBER(int, pfnFailRcV)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc, const char *pszFormat, va_list va); /** * Parser error. * * @returns VBox status code to pass upwards. * * @param pCmdHlp Pointer to the command callback structure. * @param pCmd The failing command, can be NULL but shouldn't. * @param iArg The offending argument, -1 when lazy. * @param pszExpr The expression. * @param iLine The line number. */ DECLCALLBACKMEMBER(int, pfnParserError)(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine); /** * Converts a DBGC variable to a DBGF address structure. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param pAddress The target address. */ DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress); /** * Converts a DBGF address structure to a DBGC variable. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pAddress The source address. * @param pResult The result variable. */ DECLCALLBACKMEMBER(int, pfnVarFromDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult); /** * Converts a DBGC variable to a 64-bit number. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param pu64Number Where to store the number. */ DECLCALLBACKMEMBER(int, pfnVarToNumber)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number); /** * Converts a DBGC variable to a boolean. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param pf Where to store the boolean. */ DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf); /** * Get the range of a variable in bytes, resolving symbols if necessary. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param cbElement Conversion factor for element ranges. * @param cbDefault The default range. * @param pcbRange The length of the range. */ DECLCALLBACKMEMBER(int, pfnVarGetRange)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange); /** * Converts a variable to one with the specified type. * * This preserves the range. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param enmToType The target type. * @param fConvSyms If @c true, then attempt to resolve symbols. * @param pResult The output variable. Can be the same as @a pVar. */ DECLCALLBACKMEMBER(int, pfnVarConvert)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult); /** * Gets a DBGF output helper that directs the output to the debugger * console. * * @returns Pointer to the helper structure. * @param pCmdHlp Pointer to the command callback structure. */ DECLCALLBACKMEMBER(PCDBGFINFOHLP, pfnGetDbgfOutputHlp)(PDBGCCMDHLP pCmdHlp); /** * Gets the ID currently selected CPU. * * @returns Current CPU ID. * @param pCmdHlp Pointer to the command callback structure. */ DECLCALLBACKMEMBER(VMCPUID, pfnGetCurrentCpu)(PDBGCCMDHLP pCmdHlp); /** * Gets the mode the currently selected CPU is running in, in the current * context. * * @returns Current CPU mode. * @param pCmdHlp Pointer to the command callback structure. */ DECLCALLBACKMEMBER(CPUMMODE, pfnGetCpuMode)(PDBGCCMDHLP pCmdHlp); /** End marker (DBGCCMDHLP_MAGIC). */ uint32_t u32EndMarker; } DBGCCMDHLP; /** Magic value for DBGCCMDHLP::u32Magic. (Fyodor Mikhaylovich Dostoyevsky) */ #define DBGCCMDHLP_MAGIC UINT32_C(18211111) #ifdef IN_RING3 /** * @copydoc DBGCCMDHLP::pfnPrintf */ DECLINLINE(int) DBGCCmdHlpPrintf(PDBGCCMDHLP pCmdHlp, const char *pszFormat, ...) { va_list va; int rc; va_start(va, pszFormat); rc = pCmdHlp->pfnPrintfV(pCmdHlp, NULL, pszFormat, va); va_end(va); return rc; } /** * @copydoc DBGCCMDHLP::pfnStrPrintf */ DECLINLINE(size_t) DBGCCmdHlpStrPrintf(PDBGCCMDHLP pCmdHlp, char *pszBuf, size_t cbBuf, const char *pszFormat, ...) { va_list va; size_t cch; va_start(va, pszFormat); cch = pCmdHlp->pfnStrPrintfV(pCmdHlp, pszBuf, cbBuf, pszFormat, va); va_end(va); return cch; } /** * @copydoc FNDBGCHLPVBOXERROR */ DECLINLINE(int) DBGCCmdHlpVBoxError(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...) { va_list va; va_start(va, pszFormat); rc = pCmdHlp->pfnVBoxErrorV(pCmdHlp, rc, pszFormat, va); va_end(va); return rc; } /** * @copydoc FNDBGCHLPMEMREAD */ DECLINLINE(int) DBGCCmdHlpMemRead(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead) { return pCmdHlp->pfnMemRead(pCmdHlp, pVM, pvBuffer, cbRead, pVarPointer, pcbRead); } /** * Evaluates an expression. * (Hopefully the parser and functions are fully reentrant.) * * @returns VBox status code appropriate to return from a command. * @param pCmdHlp Pointer to the command callback structure. * @param pResult Where to store the result. * @param pszExpr The expression. Format string with the format DBGC extensions. * @param ... Format arguments. */ DECLINLINE(int) DBGCCmdHlpEval(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...) { va_list va; int rc; va_start(va, pszExpr); rc = pCmdHlp->pfnEvalV(pCmdHlp, pResult, pszExpr, va); va_end(va); return rc; } /** * Print an error and fail the current command. * * @returns VBox status code to pass upwards. * * @param pCmdHlp Pointer to the command callback structure. * @param pCmd The failing command. * @param pszFormat The error message format string. * @param ... Format arguments. */ DECLINLINE(int) DBGCCmdHlpFail(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, const char *pszFormat, ...) { va_list va; int rc; va_start(va, pszFormat); rc = pCmdHlp->pfnFailV(pCmdHlp, pCmd, pszFormat, va); va_end(va); return rc; } /** * Print an error and fail the current command. * * Usage example: * @code int rc = VMMR3Something(pVM); if (RT_FAILURE(rc)) return DBGCCmdHlpFailRc(pCmdHlp, pCmd, rc, "VMMR3Something"); return VINF_SUCCESS; * @endcode * * @returns VBox status code to pass upwards. * * @param pCmdHlp Pointer to the command callback structure. * @param pCmd The failing command. * @param rc The status code indicating the failure. * @param pszFormat The error message format string. * @param ... Format arguments. */ DECLINLINE(int) DBGCCmdHlpFailRc(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int rc, const char *pszFormat, ...) { va_list va; va_start(va, pszFormat); rc = pCmdHlp->pfnFailRcV(pCmdHlp, pCmd, rc, pszFormat, va); va_end(va); return rc; } /** * @copydoc DBGCCMDHLP::pfnParserError */ DECLINLINE(int) DBGCCmdHlpParserError(PDBGCCMDHLP pCmdHlp, PCDBGCCMD pCmd, int iArg, const char *pszExpr, unsigned iLine) { return pCmdHlp->pfnParserError(pCmdHlp, pCmd, iArg, pszExpr, iLine); } /** Assert+return like macro for checking parser sanity. * Returns with failure if the precodition is not met. */ #define DBGC_CMDHLP_ASSERT_PARSER_RET(pCmdHlp, pCmd, iArg, expr) \ do { \ if (!(expr)) \ return DBGCCmdHlpParserError(pCmdHlp, pCmd, iArg, #expr, __LINE__); \ } while (0) /** Assert+return like macro that the VM handle is present. * Returns with failure if the VM handle is NIL. */ #define DBGC_CMDHLP_REQ_VM_RET(pCmdHlp, pCmd, pVM) \ do { \ if (!(pVM)) \ return DBGCCmdHlpFail(pCmdHlp, pCmd, "No VM selected"); \ } while (0) /** * @copydoc DBGCCMDHLP::pfnVarToDbgfAddr */ DECLINLINE(int) DBGCCmdHlpVarToDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress) { return pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, pAddress); } /** * @copydoc DBGCCMDHLP::pfnVarToDbgfAddr */ DECLINLINE(int) DBGCCmdHlpVarFromDbgfAddr(PDBGCCMDHLP pCmdHlp, PCDBGFADDRESS pAddress, PDBGCVAR pResult) { return pCmdHlp->pfnVarFromDbgfAddr(pCmdHlp, pAddress, pResult); } /** * Converts an variable to a flat address. * * @returns VBox status code. * @param pCmdHlp Pointer to the command callback structure. * @param pVar The variable to convert. * @param pFlatPtr Where to store the flat address. */ DECLINLINE(int) DBGCCmdHlpVarToFlatAddr(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PRTGCPTR pFlatPtr) { DBGFADDRESS Addr; int rc = pCmdHlp->pfnVarToDbgfAddr(pCmdHlp, pVar, &Addr); if (RT_SUCCESS(rc)) *pFlatPtr = Addr.FlatPtr; return rc; } /** * @copydoc DBGCCMDHLP::pfnVarToNumber */ DECLINLINE(int) DBGCCmdHlpVarToNumber(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t *pu64Number) { return pCmdHlp->pfnVarToNumber(pCmdHlp, pVar, pu64Number); } /** * @copydoc DBGCCMDHLP::pfnVarToBool */ DECLINLINE(int) DBGCCmdHlpVarToBool(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf) { return pCmdHlp->pfnVarToBool(pCmdHlp, pVar, pf); } /** * @copydoc DBGCCMDHLP::pfnVarGetRange */ DECLINLINE(int) DBGCCmdHlpVarGetRange(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, uint64_t cbElement, uint64_t cbDefault, uint64_t *pcbRange) { return pCmdHlp->pfnVarGetRange(pCmdHlp, pVar, cbElement, cbDefault, pcbRange); } /** * @copydoc DBGCCMDHLP::pfnVarConvert */ DECLINLINE(int) DBGCCmdHlpConvert(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, DBGCVARTYPE enmToType, bool fConvSyms, PDBGCVAR pResult) { return pCmdHlp->pfnVarConvert(pCmdHlp, pVar, enmToType, fConvSyms, pResult); } /** * @copydoc DBGCCMDHLP::pfnGetDbgfOutputHlp */ DECLINLINE(PCDBGFINFOHLP) DBGCCmdHlpGetDbgfOutputHlp(PDBGCCMDHLP pCmdHlp) { return pCmdHlp->pfnGetDbgfOutputHlp(pCmdHlp); } /** * @copydoc DBGCCMDHLP::pfnGetCurrentCpu */ DECLINLINE(VMCPUID) DBGCCmdHlpGetCurrentCpu(PDBGCCMDHLP pCmdHlp) { return pCmdHlp->pfnGetCurrentCpu(pCmdHlp); } /** * @copydoc DBGCCMDHLP::pfnGetCpuMode */ DECLINLINE(CPUMMODE) DBGCCmdHlpGetCpuMode(PDBGCCMDHLP pCmdHlp) { return pCmdHlp->pfnGetCpuMode(pCmdHlp); } #endif /* IN_RING3 */ /** * Command handler. * * The console will call the handler for a command once it's finished * parsing the user input. The command handler function is responsible * for executing the command itself. * * @returns VBox status. * @param pCmd Pointer to the command descriptor (as registered). * @param pCmdHlp Pointer to command helper functions. * @param pVM Pointer to the current VM (if any). * @param paArgs Pointer to (readonly) array of arguments. * @param cArgs Number of arguments in the array. */ typedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR paArgs, unsigned cArgs); /** Pointer to a FNDBGCCMD() function. */ typedef FNDBGCCMD *PFNDBGCCMD; /** * DBGC command descriptor. */ typedef struct DBGCCMD { /** Command string. */ const char *pszCmd; /** Minimum number of arguments. */ unsigned cArgsMin; /** Max number of arguments. */ unsigned cArgsMax; /** Argument descriptors (array). */ PCDBGCVARDESC paArgDescs; /** Number of argument descriptors. */ unsigned cArgDescs; /** flags. (reserved for now) */ unsigned fFlags; /** Handler function. */ PFNDBGCCMD pfnHandler; /** Command syntax. */ const char *pszSyntax; /** Command description. */ const char *pszDescription; } DBGCCMD; /** DBGCCMD Flags. * @{ */ /** @} */ /** * Function handler. * * The console will call the handler for a command once it's finished * parsing the user input. The command handler function is responsible * for executing the command itself. * * @returns VBox status. * @param pCmd Pointer to the command descriptor (as registered). * @param pCmdHlp Pointer to command helper functions. * @param pVM Pointer to the current VM (if any). * @param paArgs Pointer to (readonly) array of arguments. * @param cArgs Number of arguments in the array. * @param pResult Where to return the result. */ typedef DECLCALLBACK(int) FNDBGCFUNC(PCDBGCFUNC pFunc, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR paArgs, unsigned cArgs, PDBGCVAR pResult); /** Pointer to a FNDBGCFUNC() function. */ typedef FNDBGCFUNC *PFNDBGCFUNC; /** * DBGC function descriptor. */ typedef struct DBGCFUNC { /** Command string. */ const char *pszFuncNm; /** Minimum number of arguments. */ unsigned cArgsMin; /** Max number of arguments. */ unsigned cArgsMax; /** Argument descriptors (array). */ PCDBGCVARDESC paArgDescs; /** Number of argument descriptors. */ unsigned cArgDescs; /** flags. (reserved for now) */ unsigned fFlags; /** Handler function. */ PFNDBGCFUNC pfnHandler; /** Function syntax. */ const char *pszSyntax; /** Function description. */ const char *pszDescription; } DBGCFUNC; /** Pointer to a DBGC backend. */ typedef struct DBGCBACK *PDBGCBACK; /** * Checks if there is input. * * @returns true if there is input ready. * @returns false if there not input ready. * @param pBack Pointer to the backend structure supplied by * the backend. The backend can use this to find * it's instance data. * @param cMillies Number of milliseconds to wait on input data. */ typedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies); /** Pointer to a FNDBGCBACKINPUT() callback. */ typedef FNDBGCBACKINPUT *PFNDBGCBACKINPUT; /** * Read input. * * @returns VBox status code. * @param pBack Pointer to the backend structure supplied by * the backend. The backend can use this to find * it's instance data. * @param pvBuf Where to put the bytes we read. * @param cbBuf Maximum nymber of bytes to read. * @param pcbRead Where to store the number of bytes actually read. * If NULL the entire buffer must be filled for a * successful return. */ typedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead); /** Pointer to a FNDBGCBACKREAD() callback. */ typedef FNDBGCBACKREAD *PFNDBGCBACKREAD; /** * Write (output). * * @returns VBox status code. * @param pBack Pointer to the backend structure supplied by * the backend. The backend can use this to find * it's instance data. * @param pvBuf What to write. * @param cbBuf Number of bytes to write. * @param pcbWritten Where to store the number of bytes actually written. * If NULL the entire buffer must be successfully written. */ typedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten); /** Pointer to a FNDBGCBACKWRITE() callback. */ typedef FNDBGCBACKWRITE *PFNDBGCBACKWRITE; /** * Ready / busy notification. * * @param pBack Pointer to the backend structure supplied by * the backend. The backend can use this to find * it's instance data. * @param fReady Whether it's ready (true) or busy (false). */ typedef DECLCALLBACK(void) FNDBGCBACKSETREADY(PDBGCBACK pBack, bool fReady); /** Pointer to a FNDBGCBACKSETREADY() callback. */ typedef FNDBGCBACKSETREADY *PFNDBGCBACKSETREADY; /** * The communication backend provides the console with a number of callbacks * which can be used */ typedef struct DBGCBACK { /** Check for input. */ PFNDBGCBACKINPUT pfnInput; /** Read input. */ PFNDBGCBACKREAD pfnRead; /** Write output. */ PFNDBGCBACKWRITE pfnWrite; /** Ready / busy notification. */ PFNDBGCBACKSETREADY pfnSetReady; } DBGCBACK; /** * Make a console instance. * * This will not return until either an 'exit' command is issued or a error code * indicating connection loss is encountered. * * @returns VINF_SUCCESS if console termination caused by the 'exit' command. * @returns The VBox status code causing the console termination. * * @param pVM VM Handle. * @param pBack Pointer to the backend structure. This must contain * a full set of function pointers to service the console. * @param fFlags Reserved, must be zero. * @remark A forced termination of the console is easiest done by forcing the * callbacks to return fatal failures. */ DBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags); /** * Register one or more external commands. * * @returns VBox status. * @param paCommands Pointer to an array of command descriptors. * The commands must be unique. It's not possible * to register the same commands more than once. * @param cCommands Number of commands. */ DBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands); /** * Deregister one or more external commands previously registered by * DBGCRegisterCommands(). * * @returns VBox status. * @param paCommands Pointer to an array of command descriptors * as given to DBGCRegisterCommands(). * @param cCommands Number of commands. */ DBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands); /** * Spawns a new thread with a TCP based debugging console service. * * @returns VBox status. * @param pVM VM handle. * @param ppvData Where to store the pointer to instance data. */ DBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser); /** * Terminates any running TCP base debugger console service. * * @returns VBox status. * @param pVM VM handle. * @param pvData Instance data set by DBGCTcpCreate(). */ DBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData); /** @defgroup grp_dbgc_plug_in The DBGC Plug-in Interface * @{ */ /** The plug-in module name prefix. */ #define DBGC_PLUG_IN_PREFIX "DBGCPlugIn" /** The name of the plug-in entry point (FNDBGCPLUGIN) */ #define DBGC_PLUG_IN_ENTRYPOINT "DBGCPlugInEntry" /** * DBGC plug-in operations. */ typedef enum DBGCPLUGINOP { /** The usual invalid first value. */ DBGCPLUGINOP_INVALID, /** Initialize the plug-in, register all the stuff. * The plug-in will be unloaded on failure. * uArg: The VirtualBox version (major+minor). */ DBGCPLUGINOP_INIT, /** Terminate the plug-ing, deregister all the stuff. * The plug-in will be unloaded after this call regardless of the return * code. */ DBGCPLUGINOP_TERM, /** The usual 32-bit hack. */ DBGCPLUGINOP_32BIT_HACK = 0x7fffffff } DBGCPLUGINOP; /** * DBGC plug-in main entry point. * * @returns VBox status code. * * @param enmOperation The operation. * @param pVM The VM handle. This may be NULL. * @param uArg Extra argument. */ typedef DECLCALLBACK(int) FNDBGCPLUGIN(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg); /** Pointer to a FNDBGCPLUGIN. */ typedef FNDBGCPLUGIN *PFNDBGCPLUGIN; /** @copydoc FNDBGCPLUGIN */ DECLEXPORT(int) DBGCPlugInEntry(DBGCPLUGINOP enmOperation, PVM pVM, uintptr_t uArg); #endif /* IN_RING3 */ /** @} */ RT_C_DECLS_END #endif