dbgf.h revision fb4eb94aa480fd7c55e913ad203a7f3dd002271e
2N/A * DBGF - Debugging Facility. 2N/A * Copyright (C) 2006-2007 innotek GmbH 2N/A * This file is part of VirtualBox Open Source Edition (OSE), as 2N/A * you can redistribute it and/or modify it under the terms of the GNU 2N/A * General Public License as published by the Free Software Foundation, 2N/A * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE 2N/A * distribution. VirtualBox OSE is distributed in the hope that it will 2N/A * be useful, but WITHOUT ANY WARRANTY of any kind. 2N/A/** @defgroup grp_dbgf The Debugging Facility API /** @addgroup grp_dbgf_gc The GC DBGF API * \#DB (Debug event) handler. * @returns VBox status code. * VINF_SUCCESS means we completely handled this trap, * other codes are passed execution to host context. * @param pVM The VM handle. * @param pRegFrame Pointer to the register frame for the trap. * @param uDr6 The DR6 register value. * \#BP (Breakpoint) handler. * @returns VBox status code. * VINF_SUCCESS means we completely handled this trap, * other codes are passed execution to host context. * @param pVM The VM handle. * @param pRegFrame Pointer to the register frame for the trap. /** @addgroup grp_dbgf_gc The R0 DBGF API * \#DB (Debug event) handler. * @returns VBox status code. * VINF_SUCCESS means we completely handled this trap, * other codes are passed execution to host context. * @param pVM The VM handle. * @param pRegFrame Pointer to the register frame for the trap. * @param uDr6 The DR6 register value. * \#BP (Breakpoint) handler. * @returns VBox status code. * VINF_SUCCESS means we completely handled this trap, * other codes are passed execution to host context. * @param pVM The VM handle. * @param pRegFrame Pointer to the register frame for the trap. /** The selector offset address. */ /** The selector. DBGF_SEL_FLAT is a legal value. */ /** Flags describing further details about the address. */ /** Pointer to a mixed address. */ /** Pointer to a const mixed address. */ /** @name DBGFADDRESS Flags. /** A 16:16 far address. */ /** A 16:32 far address. */ /** A 16:64 far address. */ /** A physical address. */ /** The address type mask. */ /** Set if the address is valid. */ /** The address is within the hypervisor memoary area (HMA). * If not set, the address can be assumed to be a guest address. */ /** Checks if the mixed address is flat or not. */ /** Checks if the mixed address is flat or not. */ /** Checks if the mixed address is far 16:16 or not. */ /** Checks if the mixed address is far 16:32 or not. */ /** Checks if the mixed address is far 16:64 or not. */ /** Checks if the mixed address is valid. */ /** Checks if the address is flagged as within the HMA. */ * Creates a mixed address from a Sel:off pair. * @returns VBox status code. * @param pVM The VM handle. * @param pAddress Where to store the mixed address. * @param Sel The selector part. * @param off The offset part. * Creates a mixed address from a flat address. * @param pVM The VM handle. * @param pAddress Where to store the mixed address. * @param FlatPtr The flat pointer. * Creates a mixed address from a guest physical address. * @param pVM The VM handle. * @param pAddress Where to store the mixed address. * @param PhysAddr The guest physical address. * Checks if the specified address is valid (checks the structure pointer too). * @returns true if valid. * @returns false if invalid. * @param pVM The VM handle. * @param pAddress The address to validate. * This notifies that a halt command have been successfully completed. * This notifies that the detach command have been successfully completed. /** The command from the debugger is not recognized. * This means internal error or half implemented features. * This notifies a fatal error in the VMM and that the debugger get's a * chance to first hand information about the the problem. * This notifies that a breakpoint installed by the debugger was hit. The * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member. /** Breakpoint Hit in the Hypervisor. * This notifies that a breakpoint installed by the debugger was hit. The * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member. /** Assertion in the Hypervisor (breakpoint instruction). * This notifies that a breakpoint instruction was hit in the hypervisor context. * This notifies that a single step operation was completed. * This notifies that a hypervisor single step operation was completed. /** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function * to bring up the debugger at a specific place. /** The VM is terminating. * When this notification is received, the debugger thread should detach ASAP. /** The usual 32-bit hack. */ * The context of an event. /** The usual invalid entry. */ /** Hypervisor context. */ /** The usual 32-bit hack */ /** Type specific data. */ /** Fatal error details. */ /** The GC return code. */ /** Assertion messages. */ /** The first message. */ /** The second message. */ /** The identifier of the breakpoint which was hit. */ /** Padding for ensuring that the structure is 8 byte aligned. */ /** Pointer to VMM Debug Event. */ /** Pointer to const VMM Debug Event. */ * Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event. * @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS. * @returns VBox status code. * Termiantes and cleans up resources allocated by the DBGF. * @returns VBox status code. * Applies relocations to data and code managed by this * component. This function will be called at init and * whenever the VMM need to relocate it self inside the GC. * @param offDelta Relocation delta relative to old location. * Forced action callback. * The VMM will call this from it's main loop when VM_FF_DBGF is set. * The function checks and executes pending commands from the debugger. * @returns VINF_SUCCESS normally. * @returns VERR_DBGF_RAISE_FATAL_ERROR to pretend a fatal error happend. * Send a generic debugger event which takes no data. * @param pVM The VM handle. * @param enmEvent The event to send. * Send a debugger event which takes the full source file location. * @param pVM The VM handle. * @param enmEvent The event to send. * @param pszFile Source file. * @param uLine Line number in source file. * @param pszFunction Function name. * @param pszFormat Message which accompanies the event. * @param ... Message arguments. * Send a debugger event which takes the full source file location. * @param pVM The VM handle. * @param enmEvent The event to send. * @param pszFile Source file. * @param uLine Line number in source file. * @param pszFunction Function name. * @param pszFormat Message which accompanies the event. * @param args Message arguments. * Send a debugger event which takes the two assertion messages. * @param pVM The VM handle. * @param enmEvent The event to send. * @param pszMsg1 First assertion message. * @param pszMsg2 Second assertion message. * Breakpoint was hit somewhere. * Figure out which breakpoint it is and notify the debugger. * @param pVM The VM handle. * @param enmEvent DBGFEVENT_BREAKPOINT_HYPER or DBGFEVENT_BREAKPOINT. * Attaches a debugger to the specified VM. * Only one debugger at a time. * @returns VBox status code. * Detaches a debugger from the specified VM. * Caller must be attached to the VM. * @returns VBox status code. * Wait for a debug event. * @returns VBox status. Will not return VBOX_INTERRUPTED. * @param cMillies Number of millies to wait. * @param ppEvent Where to store the event pointer. * After calling this the VM isn't actually halted till an DBGFEVENT_HALT_DONE * arrives. Until that time it's not possible to issue any new commands. * Checks if the VM is halted by the debugger. * @returns True if halted. * @returns False if not halted. * Checks if the the debugger can wait for events or not. * This function is only used by lazy, multiplexing debuggers. :-) * @returns True if waitable. * @returns False if not waitable. * There is no receipt event on this command. * A single step event is generated from this command. * The current implementation is not reliable, so don't rely on the event comming. * Call this to single step rawmode or recompiled mode. * You must pass down the return code to the EM loop! That's * where the actual single stepping take place (at least in the * current implementation). * @returns VINF_EM_DBG_STEP /** Free breakpoint entry. */ /** INT 3 instruction. */ /** ensure 32-bit size. */ /** The number of breakpoint hits. */ /** The hit number which starts to trigger the breakpoint. */ /** The hit number which stops triggering the breakpoint (disables it). * Use ~(uint64_t)0 if it should never stop. */ /** The Flat GC address of the breakpoint. * (PC register value if REM type?) */ /** The breakpoint id. */ /** The breakpoint status - enabled or disabled. */ /** The breakpoint type. */ /** Union of type specific data. */ /** Debug register data. */ /** The debug register number. */ /** The access type (one of the X86_DR7_RW_* value). */ /** Recompiler breakpoint data. */ /** The byte value we replaced by the INT 3 instruction. */ /** Recompiler breakpoint data. */ /** Paddind to ensure that the size is identical on win32 and linux. */ /** Pointer to a breakpoint. */ /** Pointer to a const breakpoint. */ * Sets a breakpoint (int 3 based). * @returns VBox status code. * @param pVM The VM handle. * @param pAddress The address of the breakpoint. * @param iHitTrigger The hit count at which the breakpoint start triggering. * Use 0 (or 1) if it's gonna trigger at once. * @param iHitDisable The hit count which disables the breakpoint. * Use ~(uint64_t) if it's never gonna be disabled. * @param piBp Where to store the breakpoint id. (optional) * Sets a register breakpoint. * @returns VBox status code. * @param pVM The VM handle. * @param pAddress The address of the breakpoint. * @param iHitTrigger The hit count at which the breakpoint start triggering. * Use 0 (or 1) if it's gonna trigger at once. * @param iHitDisable The hit count which disables the breakpoint. * Use ~(uint64_t) if it's never gonna be disabled. * @param fType The access type (one of the X86_DR7_RW_* defines). * @param cb The access size - 1,2,4 or 8 (the latter is AMD64 long mode only. * Must be 1 if fType is X86_DR7_RW_EO. * @param piBp Where to store the breakpoint id. (optional) * Sets a recompiler breakpoint. * @returns VBox status code. * @param pVM The VM handle. * @param pAddress The address of the breakpoint. * @param iHitTrigger The hit count at which the breakpoint start triggering. * Use 0 (or 1) if it's gonna trigger at once. * @param iHitDisable The hit count which disables the breakpoint. * Use ~(uint64_t) if it's never gonna be disabled. * @param piBp Where to store the breakpoint id. (optional) * @returns VBox status code. * @param pVM The VM handle. * @param iBp The id of the breakpoint which should be removed (cleared). * @returns VBox status code. * @param pVM The VM handle. * @param iBp The id of the breakpoint which should be enabled. * @returns VBox status code. * @param pVM The VM handle. * @param iBp The id of the breakpoint which should be disabled. * Breakpoint enumeration callback function. * @returns VBox status code. Any failure will stop the enumeration. * @param pVM The VM handle. * @param pvUser The user argument. * @param pBp Pointer to the breakpoint information. (readonly) /** Pointer to a breakpoint enumeration callback function. */ * Enumerate the breakpoints. * @returns VBox status code. * @param pVM The VM handle. * @param pfnCallback The callback function. * @param pvUser The user argument to pass to the callback. * @thread Any thread but the callback will be called from EMT. * Gets the hardware breakpoint configuration as DR7. * @returns DR7 from the DBGF point of view. * @param pVM The VM handle. * Gets the address of the hardware breakpoint number 0. * @returns DR0 from the DBGF point of view. * @param pVM The VM handle. * Gets the address of the hardware breakpoint number 1. * @returns DR1 from the DBGF point of view. * @param pVM The VM handle. * Gets the address of the hardware breakpoint number 2. * @returns DR2 from the DBGF point of view. * @param pVM The VM handle. * Gets the address of the hardware breakpoint number 3. * @returns DR3 from the DBGF point of view. * @param pVM The VM handle. * Returns single stepping state * @returns stepping or not * @param pVM The VM handle. /** Pointer to a info helper callback structure. */ /** Pointer to a const info helper callback structure. */ * Info helper callback structure. * Print formatted string. * @param pHlp Pointer to this structure. * @param pszFormat The format string. * Print formatted string. * @param pHlp Pointer to this structure. * @param pszFormat The format string. * @param args Argument list. * Info handler, device version. * @param pDevIns Device instance which registered the info. * @param pHlp Callback functions for doing output. * @param pszArgs Argument string. Optional and specific to the handler. /** Pointer to a FNDBGFHANDLERDEV function. */ * Info handler, driver version. * @param pDrvIns Driver instance which registered the info. * @param pHlp Callback functions for doing output. * @param pszArgs Argument string. Optional and specific to the handler. /** Pointer to a FNDBGFHANDLERDRV function. */ * Info handler, internal version. * @param pVM The VM handle. * @param pHlp Callback functions for doing output. * @param pszArgs Argument string. Optional and specific to the handler. /** Pointer to a FNDBGFHANDLERINT function. */ * Info handler, external version. * @param pvUser User argument. * @param pHlp Callback functions for doing output. * @param pszArgs Argument string. Optional and specific to the handler. /** Pointer to a FNDBGFHANDLEREXT function. */ /** @name Flags for the info registration functions. /** The handler must run on the EMT. */ * Register a info handler owned by a device. * @returns VBox status code. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * @param pDevIns The device instance owning the info. * Register a info handler owned by a driver. * @returns VBox status code. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * @param pDrvIns The driver instance owning the info. * Register a info handler owned by an internal component. * @returns VBox status code. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * Register a info handler owned by an internal component. * @returns VBox status code. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * @param fFlags Flags, see the DBGFINFO_FLAGS_*. * Register a info handler owned by an external component. * @returns VBox status code. * @param pszName The identifier of the info. * @param pszDesc The description of the info and any arguments the handler may take. * @param pfnHandler The handler function to be called to display the info. * @param pvUser User argument to be passed to the handler. * Deregister one(/all) info handler(s) owned by a device. * @returns VBox status code. * @param pDevIns Device instance. * @param pszName The identifier of the info. If NULL all owned by the device. * Deregister one(/all) info handler(s) owned by a driver. * @returns VBox status code. * @param pDrvIns Driver instance. * @param pszName The identifier of the info. If NULL all owned by the driver. * Deregister a info handler owned by an internal component. * @returns VBox status code. * @param pszName The identifier of the info. If NULL all owned by the device. * Deregister a info handler owned by an external component. * @returns VBox status code. * @param pszName The identifier of the info. If NULL all owned by the device. * Display a piece of info writing to the supplied handler. * @returns VBox status code. * @param pszName The identifier of the info to display. * @param pszArgs Arguments to the info handler. * @param pHlp The output helper functions. If NULL the logger will be used. * Display a piece of info writing to the log if enabled. * @param pszName The identifier of the info to display. * @param pszArgs Arguments to the info handler. * Changes the logger group settings. * @returns VBox status code. * @param pVM The VM handle. * @param pszGroupSettings The group settings string. (VBOX_LOG) * Changes the logger flag settings. * @returns VBox status code. * @param pVM The VM handle. * @param pszFlagSettings The flag settings string. (VBOX_LOG_FLAGS) * Changes the logger destination settings. * @returns VBox status code. * @param pVM The VM handle. * @param pszDestSettings The destination settings string. (VBOX_LOG_DEST) * Enumeration callback for use with DBGFR3InfoEnum. * @returns VBox status code. * A status code indicating failure will end the enumeration * and DBGFR3InfoEnum will return with that status code. * @param pszName Info identifier name. * @param pszDesc The description. /** Pointer to a FNDBGFINFOENUM function. */ * Enumerate all the register info handlers. * @returns VBox status code. * @param pfnCallback Pointer to callback function. * @param pvUser User argument to pass to the callback. * Gets the logger info helper. * The returned info helper will unconditionally write all output to the log. * @returns Pointer to the logger info helper. * Gets the release logger info helper. * The returned info helper will unconditionally write all output to the release log. * @returns Pointer to the release logger info helper. /** Max length (including '\\0') of a symbol name. */ /** Symbol value (address). */ /** Symbol Flags. (reserved). */ /** Pointer to debug symbol. */ /** Pointer to const debug symbol. */ * Debug line number information. /** Pointer to debug line number. */ /** Pointer to const debug line number. */ * Load debug info, optionally related to a specific module. * @param pszFilename Path to the file containing the symbol information. * This can be the executable image, a flat symbol file of some kind or stripped debug info. * @param AddressDelta The value to add to the loaded symbols. * @param pszName Short hand name for the module. If not related to a module specify NULL. * @param Address Address which the image is loaded at. This will be used to reference the module other places in the api. * Ignored when pszName is NULL. * @param cbImage Size of the image. * Ignored when pszName is NULL. * Interface used by PDMR3LdrRelocate for telling us that a GC module has been relocated. * @param pVM The VM handle. * @param OldImageBase The old image base. * @param NewImageBase The new image base. * @param cbImage The image size. * @param pszFilename The image filename. * @param pszName The module name. * Adds a symbol to the debug info manager. * @param ModuleAddress Module address. Use 0 if no module. * @param SymbolAddress Symbol address * @param cbSymbol Size of the symbol. Use 0 if info not available. * @param pszSymbol Symbol name. * Find symbol by address (nearest). * @param Address Address. * @param poffDisplacement Where to store the symbol displacement from Address. * @param pSymbol Where to store the symbol info. * Find symbol by name (first). * @param pszSymbol Symbol name. * @param pSymbol Where to store the symbol info. * Find symbol by address (nearest), allocate return buffer. * @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree(). * @returns NULL if the symbol was not found or if we're out of memory. * @param Address Address. * @param poffDisplacement Where to store the symbol displacement from Address. * Find symbol by name (first), allocate return buffer. * @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree(). * @returns NULL if the symbol was not found or if we're out of memory. * @param pszSymbol Symbol name. * @param ppSymbol Where to store the pointer to the symbol info. * Frees a symbol returned by DBGFR3SymbolbyNameAlloc() or DBGFR3SymbolByAddressAlloc(). * @param pSymbol Pointer to the symbol. * Find line by address (nearest). * @param Address Address. * @param poffDisplacement Where to store the line displacement from Address. * @param pLine Where to store the line info. * Find line by address (nearest), allocate return buffer. * @returns Pointer to the line. Must be freed using DBGFR3LineFree(). * @returns NULL if the line was not found or if we're out of memory. * @param Address Address. * @param poffDisplacement Where to store the line displacement from Address. * Frees a line returned by DBGFR3LineByAddressAlloc(). * @param pLine Pointer to the line. /** The usual invalid 0 value. */ /** Near 16-bit return. */ /** Near 32-bit return. */ /** Near 64-bit return. */ /** 16-bit iret return (e.g. real or 286 protect mode). */ /** 32-bit iret return. */ /** 32-bit iret return. */ /** 32-bit iret return to V86 mode. */ /** @todo 64-bit iret return. */ /** The usual 32-bit blowup. */ * Figures the size of the return state on the stack. * @returns number of bytes. 0 if invalid parameter. * @param enmRetType The type of return. /** Pointer to stack frame info. */ * Info about a stack frame. * The off member is [e|r]bp and the Sel member is ss. */ /** The stack address of the frame. * The off member is [e|r]sp and the Sel member is ss. */ /** The program counter (PC) address of the frame. * The off member is [e|r]ip and the Sel member is cs. */ /** Pointer to the symbol nearest the program counter (PC). NULL if not found. */ /** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */ /** The return frame address. * The off member is [e|r]bp and the Sel member is ss. */ /** The return stack address. * The off member is [e|r]sp and the Sel member is ss. */ /** The way this frame returns to the next one. */ /** The program counter (PC) address which the frame returns to. * The off member is [e|r]ip and the Sel member is cs. */ /** Pointer to the symbol nearest the return PC. NULL if not found. */ /** Pointer to the linnumber nearest the return PC. NULL if not found. */ /** 32-bytes of stack arguments. */ /** Pointer to the next frame. * Might not be used in some cases, so consider it internal. */ /** Pointer to the first frame. * Might not be used in some cases, so consider it internal. */ /** @name DBGFSTACKFRAME Flags. /** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used * to construct the next frame. */ /** This is the last stack frame we can read. * This flag is not set if the walk stop because of max dept or recursion. */ /** This is the last record because we detected a loop. */ /** This is the last record because we reached the maximum depth. */ * This will construct and obtain the first frame. * @returns VINF_SUCCESS on success. * @returns VERR_NO_MEMORY if we're out of memory. * @param pVM The VM handle. * @param pFrame The stack frame info structure. * On input this structure must be memset to zero. * If wanted, the AddrPC, AddrStack and AddrFrame fields may be set * to valid addresses after memsetting it. Any of those fields not set * will be fetched from the guest CPU state. * On output the structure will contain all the information we were able to * obtain about the stack frame. * This will construct and obtain the first frame. * @returns VINF_SUCCESS on success. * @returns VERR_NO_MEMORY if we're out of memory. * @param pVM The VM handle. * @param pFrame The stack frame info structure. * On input this structure must be memset to zero. * If wanted, the AddrPC, AddrStack and AddrFrame fields may be set * to valid addresses after memsetting it. Any of those fields not set * will be fetched from the hypervisor CPU state. * On output the structure will contain all the information we were able to * obtain about the stack frame. * Gets the next stack frame. * @returns VERR_NO_MORE_FILES if not more stack frames. * @param pVM The VM handle. * @param pFrame Pointer to the current frame on input, content is replaced with the next frame on successful return. * Ends a stack walk process. * This *must* be called after a successful first call to any of the stack * walker functions. If not called we will leak memory or other resources. * @param pVM The VM handle. * @param pFrame The stackframe as returned by the last stack walk call. /** Flags to pass to DBGFR3DisasInstrEx(). /** Disassemble the current guest instruction, with annotations. */ /** Disassemble the current hypervisor instruction, with annotations. */ /** No annotations for current context. */ /** No instruction bytes. */ /** No address in the output. */ /** Special flat selector. */ * Disassembles the one instruction according to the specified flags and address. * @returns VBox status code. * @param Sel The code selector. This used to determin the 32/16 bit ness and * calculation of the actual instruction address. * Use DBGF_SEL_FLAT for specifying a flat address. * @param GCPtr The code address relative to the base of Sel. * @param fFlags Flags controlling where to start and how to format. * A combination of the DBGF_DISAS_FLAGS_* #defines. * @param pszOutput Output buffer. * @param cchOutput Size of the output buffer. * @param pcbInstr Where to return the size of the instruction. * Disassembles the current instruction. * Addresses will be tried resolved to symbols * @returns VBox status code. * @param Sel The code selector. This used to determin the 32/16 bit ness and * calculation of the actual instruction address. * Use DBGF_SEL_FLAT for specifying a flat address. * @param GCPtr The code address relative to the base of Sel. * @param pszOutput Output buffer. * @param cbOutput Size of the output buffer. * Disassembles the current instruction. * All registers and data will be displayed. Addresses will be attempted resolved to symbols * @returns VBox status code. * @param pszOutput Output buffer. * @param cbOutput Size of the output buffer. * Disassembles the current guest context instruction and writes it to the log. * All registers and data will be displayed. Addresses will be attempted resolved to symbols. * @returns VBox status code. * @param pszPrefix Short prefix string to the dissassembly string. (optional) /** @def DBGFR3DisasInstrCurrentLog * Disassembles the current guest context instruction and writes it to the log. * All registers and data will be displayed. Addresses will be attempted resolved to symbols. * Disassembles the specified guest context instruction and writes it to the log. * Addresses will be attempted resolved to symbols. * @returns VBox status code. * @param Sel The code selector. This used to determin the 32/16 bit-ness and * calculation of the actual instruction address. * @param GCPtr The code address relative to the base of Sel. /** @def DBGFR3DisasInstrLog * Disassembles the specified guest context instruction and writes it to the log. * Addresses will be attempted resolved to symbols. * Scan guest memory for an exact byte string. * @returns VBox status codes: * @retval VINF_SUCCESS and *pGCPtrHit on success. * @retval VERR_DBGF_MEM_NOT_FOUND if not found. * @retval VERR_INVALID_POINTER if any of the pointer arguments are invalid. * @retval VERR_INVALID_ARGUMENT if any other arguments are invalid. * @param pVM The VM handle. * @param pAddress Where to store the mixed address. * @param cbRange The number of bytes to scan. * @param pabNeedle What to search for - exact search. * @param cbNeedle Size of the search byte string. * @param pHitAddress Where to put the address of the first hit.