dbg.h revision c97989161fbe75bc14cea477a5443bbf474dd3ad
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Debugger Interfaces.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This header covers all external interfaces of the Debugger module.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * However, it does not cover the DBGF interface since that part of the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * VMM. Use dbgf.h for that.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Copyright (C) 2006-2007 innotek GmbH
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * available from http://www.virtualbox.org. This file is free software;
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * you can redistribute it and/or modify it under the terms of the GNU
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * General Public License as published by the Free Software Foundation,
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * distribution. VirtualBox OSE is distributed in the hope that it will
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * be useful, but WITHOUT ANY WARRANTY of any kind.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If you received this file as part of a commercial VirtualBox
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * distribution, then only the terms of your commercial VirtualBox
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * license agreement apply instead of the previous paragraph.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** @def VBOX_WITH_DEBUGGER
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * The build is with debugger module. Test if this is defined before
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * registering external debugger commands.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGC variable category.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Used to describe an argument to a command or function and a functions
d7dbbf62e47482dad97a2d17ae567e879b5d57b6vboxsync * return value.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Any type is fine. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Any kind of pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Any kind of pointer with no range option. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** GC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** GC pointer with no range option. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Numeric argument. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Numeric argument with no range option. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** String. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Symbol. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGC variable type.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** unknown... */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Flat GC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Segmented GC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Physical GC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Flat HC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Segmented HC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Physical HC pointer. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** String. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Number. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Symbol. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Special type used when querying symbols. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Checks if the specified variable type is of a pointer persuasion. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync#define DBGCVAR_ISPOINTER(enmType) (enmType >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Checks if the specified variable type is of a pointer persuasion and of the guest context sort. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync#define DBGCVAR_ISGCPOINTER(enmType) (enmType >= DBGCVAR_TYPE_GC_FLAT && enmType <= DBGCVAR_TYPE_GC_PHYS)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Checks if the specified variable type is of a pointer persuasion and of the host context sort. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync#define DBGCVAR_ISHCPOINTER(enmType) (enmType >= DBGCVAR_TYPE_HC_FLAT && enmType <= DBGCVAR_TYPE_HC_PHYS)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGC variable range type.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** No range appliable or no range specified. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Number of elements. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Number of bytes. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Variable descriptor.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef struct DBGCVARDESC
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** The minimal number of times this argument may occur.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Use 0 here to inidicate that the argument is optional. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Maximum number of occurences.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Use ~0 here to indicate infinite. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Argument category. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Flags, DBGCVD_FLAGS_* */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Argument name. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync const char *pszName;
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Argument name. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to an argument descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a const argument descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Variable descriptor flags.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Indicates that the variable depends on the previous being present. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGC variable.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef struct DBGCVAR
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to the argument descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to the next argument. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Argument type. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Type specific. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Flat GC Address. (DBGCVAR_TYPE_GC_FLAT) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Far (16:32) GC Address. (DBGCVAR_TYPE_GC_FAR) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Physical GC Address. (DBGCVAR_TYPE_GC_PHYS) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Flat HC Address. (DBGCVAR_TYPE_HC_FLAT) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Far (16:32) HC Address. (DBGCVAR_TYPE_HC_FAR) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Physical GC Address. (DBGCVAR_TYPE_HC_PHYS) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** String. (DBGCVAR_TYPE_STRING)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * The basic idea is the the this is a pointer to the expression we're
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * parsing, so no messing with freeing. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Number. (DBGCVAR_TYPE_NUMBER) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Range type. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Range. The use of the content depends on the enmRangeType. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a command argument. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a const command argument. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to helper functions for commands. */
0ffa3979e9b800f5931dd30c51ec3c0aadc3a1f1vboxsync * Command helper for writing text to the debug console.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvBuf What to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cbBuf Number of bytes to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcbWritten Where to store the number of bytes actually written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If NULL the entire buffer must be successfully written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPWRITE(PDBGCCMDHLP pCmdHlp, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPWRITE() function. */
2b114c590cf5a19f8047cd7bde9c7e5ae00aa22bvboxsync * Command helper for writing formatted text to the debug console.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcb Where to store the number of bytes written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszFormat The format string.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This is using the log formatter, so it's format extensions can be used.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param ... Arguments specified in the format string.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPPRINTF(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, ...);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPPRINTF() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command helper for writing formatted text to the debug console.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcb Where to store the number of bytes written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszFormat The format string.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This is using the log formatter, so it's format extensions can be used.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param args Arguments specified in the format string.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPPRINTFV(PDBGCCMDHLP pCmdHlp, size_t *pcbWritten, const char *pszFormat, va_list args);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPPRINTFV() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command helper for formatting and error message for a VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param rc The VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcb Where to store the number of bytes written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszFormat Format string for additional messages. Can be NULL.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param ... Format arguments, optional.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPVBOXERROR(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, ...);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPVBOXERROR() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command helper for formatting and error message for a VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param rc The VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcb Where to store the number of bytes written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszFormat Format string for additional messages. Can be NULL.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param args Format arguments, optional.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPVBOXERRORV(PDBGCCMDHLP pCmdHlp, int rc, const char *pszFormat, va_list args);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPVBOXERRORV() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command helper for reading memory specified by a DBGC variable.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM VM handle if GC or physical HC address.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvBuffer Where to store the read data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cbRead Number of bytes to read.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVarPointer DBGC variable specifying where to start reading.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcbRead Where to store the number of bytes actually read.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This optional, but it's useful when read GC virtual memory where a
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * page in the requested range might not be present.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If not specified not-present failure or end of a HC physical page
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * will cause failure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPMEMREAD(PDBGCCMDHLP pCmdHlp, PVM pVM, void *pvBuffer, size_t cbRead, PCDBGCVAR pVarPointer, size_t *pcbRead);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPMEMREAD() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command helper for writing memory specified by a DBGC variable.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM VM handle if GC or physical HC address.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvBuffer What to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cbWrite Number of bytes to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVarPointer DBGC variable specifying where to start reading.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcbWritten Where to store the number of bytes written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This is optional. If NULL be aware that some of the buffer
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * might have been written to the specified address.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPMEMWRITE(PDBGCCMDHLP pCmdHlp, PVM pVM, const void *pvBuffer, size_t cbWrite, PCDBGCVAR pVarPointer, size_t *pcbWritten);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPMEMWRITE() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Evaluates an expression.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * (Hopefully the parser and functions are fully reentrant.)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pResult Where to store the result.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszExpr The expression. Format string with the format DBGC extensions.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param ... Format arguments.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPEVAL(PDBGCCMDHLP pCmdHlp, PDBGCVAR pResult, const char *pszExpr, ...);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPEVAL() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Executes command an expression.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * (Hopefully the parser and functions are fully reentrant.)
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code appropriate to return from a command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pszExpr The expression. Format string with the format DBGC extensions.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param ... Format arguments.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCHLPEXEC(PDBGCCMDHLP pCmdHlp, const char *pszExpr, ...);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCHLPEVAL() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Helper functions for commands.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef struct DBGCCMDHLP
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBCHLPWRITE() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPPRINTF() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPPRINTFV() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPVBOXERROR() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPVBOXERRORV() function. */
aec6fc9d2efe16d4e250b2ebaf8dbfbd49f8eaa6vboxsync /** Pointer to a FNDBGCHLPMEMREAD() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPMEMWRITE() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPEVAL() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Pointer to a FNDBGCHLPEXEC() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Converts a DBGC variable to a DBGF address structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVar The variable to convert.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pAddress The target address.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync DECLCALLBACKMEMBER(int, pfnVarToDbgfAddr)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, PDBGFADDRESS pAddress);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Converts a DBGC variable to a boolean.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to the command callback structure.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVar The variable to convert.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pf Where to store the boolean.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync DECLCALLBACKMEMBER(int, pfnVarToBool)(PDBGCCMDHLP pCmdHlp, PCDBGCVAR pVar, bool *pf);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to command descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to const command descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Command handler.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * The console will call the handler for a command once it's finished
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * parsing the user input. The command handler function is responsible
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * for executing the command itself.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmd Pointer to the command descriptor (as registered).
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pCmdHlp Pointer to command helper functions.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM Pointer to the current VM (if any).
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param paArgs Pointer to (readonly) array of arguments.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cArgs Number of arguments in the array.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pResult Where to store the result. NULL if no result descriptor was specified.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCCMD(PCDBGCCMD pCmd, PDBGCCMDHLP pCmdHlp, PVM pVM, PCDBGCVAR pArgs, unsigned cArgs, PDBGCVAR pResult);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCCMD() function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGC command descriptor.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If a pResultDesc is specified the command can be called and used
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * as a function too. If it's a pure function, set fFlags to
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGCCMD_FLAGS_FUNCTION.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef struct DBGCCMD
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Command string. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync const char *pszCmd;
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Minimum number of arguments. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Max number of arguments. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Argument descriptors (array). */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Number of argument descriptors. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Result descriptor. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** flags. (reserved for now) */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Handler function. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Command syntax. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Command description. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** DBGCCMD Flags.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** The description is of a pure function which cannot be invoked
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * as a command from the commandline. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a DBGC backend. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Checks if there is input.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns true if there is input ready.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns false if there not input ready.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pBack Pointer to the backend structure supplied by
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * the backend. The backend can use this to find
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * it's instance data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cMillies Number of milliseconds to wait on input data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(bool) FNDBGCBACKINPUT(PDBGCBACK pBack, uint32_t cMillies);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCBACKINPUT() callback. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Read input.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pBack Pointer to the backend structure supplied by
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * the backend. The backend can use this to find
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * it's instance data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvBuf Where to put the bytes we read.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cbBuf Maximum nymber of bytes to read.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcbRead Where to store the number of bytes actually read.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If NULL the entire buffer must be filled for a
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * successful return.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCBACKREAD(PDBGCBACK pBack, void *pvBuf, size_t cbBuf, size_t *pcbRead);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCBACKREAD() callback. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Write (output).
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status code.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pBack Pointer to the backend structure supplied by
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * the backend. The backend can use this to find
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * it's instance data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvBuf What to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cbBuf Number of bytes to write.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pcbWritten Where to store the number of bytes actually written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * If NULL the entire buffer must be successfully written.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef DECLCALLBACK(int) FNDBGCBACKWRITE(PDBGCBACK pBack, const void *pvBuf, size_t cbBuf, size_t *pcbWritten);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync/** Pointer to a FNDBGCBACKWRITE() callback. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * The communication backend provides the console with a number of callbacks
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * which can be used
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsynctypedef struct DBGCBACK
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Check for input. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Read input. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync /** Write output. */
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Make a console instance.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * This will not return until either an 'exit' command is issued or a error code
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * indicating connection loss is encountered.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VINF_SUCCESS if console termination caused by the 'exit' command.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns The VBox status code causing the console termination.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM VM Handle.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pBack Pointer to the backend structure. This must contain
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * a full set of function pointers to service the console.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param fFlags Reserved, must be zero.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @remark A forced termination of the console is easiest done by forcing the
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * callbacks to return fatal failures.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsyncDBGDECL(int) DBGCCreate(PVM pVM, PDBGCBACK pBack, unsigned fFlags);
aec6fc9d2efe16d4e250b2ebaf8dbfbd49f8eaa6vboxsync * Register one or more external commands.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
aec6fc9d2efe16d4e250b2ebaf8dbfbd49f8eaa6vboxsync * @param paCommands Pointer to an array of command descriptors.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * The commands must be unique. It's not possible
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * to register the same commands more than once.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cCommands Number of commands.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsyncDBGDECL(int) DBGCRegisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Deregister one or more external commands previously registered by
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * DBGCRegisterCommands().
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param paCommands Pointer to an array of command descriptors
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * as given to DBGCRegisterCommands().
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param cCommands Number of commands.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsyncDBGDECL(int) DBGCDeregisterCommands(PCDBGCCMD paCommands, unsigned cCommands);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Spawns a new thread with a TCP based debugging console service.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM VM handle.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param ppvData Where to store the pointer to instance data.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsyncDBGDECL(int) DBGCTcpCreate(PVM pVM, void **ppvUser);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * Terminates any running TCP base debugger consolse service.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @returns VBox status.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pVM VM handle.
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync * @param pvData Instance data set by DBGCTcpCreate().
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsyncDBGDECL(int) DBGCTcpTerminate(PVM pVM, void *pvData);
930b5f872e89407f445d4000d4e4aaecaa6a0998vboxsync#endif /* __VBox_dbg_h__ */