vddbg.h revision 3f8f486a6133cd77aaa32bb47908a351ee14a967
/** @file
* VD Debug API.
*/
/*
* Copyright (C) 2011 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___VBox_VDDbg_h
#define ___VBox_VDDbg_h
#ifdef IN_RING0
# error "There are no VD Debug APIs available in Ring-0 Host Context!"
#endif
/** @defgroup grp_vddbg VD Debug API
* @{
*/
/** I/O logger handle. */
typedef struct VDIOLOGGERINT *VDIOLOGGER;
/** Pointer to an I/O logger handler. */
typedef VDIOLOGGER *PVDIOLOGGER;
/** Pointer to an I/O log entry handle. */
typedef struct VDIOLOGENTINT *VDIOLOGENT;
/** Pointer to an I/O log entry handle. */
typedef VDIOLOGENT *PVDIOLOGENT;
/** I/O logger buffers all log entries in memory until VDDbgIoLogCommit() is called.
* If not given all entries are immediately logged to the file. */
#define VDDBG_IOLOG_MEMORY_BUFFER RT_BIT_32(0)
/** I/O logger logs the written data. */
/** I/O logger logs the read data. */
/** I/O logger logs all data. */
/** Mask of valid flags. */
/**
* I/O direction.
*/
typedef enum VDDBGIOLOGREQ
{
/** Invalid direction. */
/** Read. */
/** Write. */
/** Flush. */
/** Discard. */
/** 32bit hack. */
VDDBGIOLOGREQ_32BIT_HACK = 0x7fffffff
/** Pointer to a I/O direction. */
typedef VDDBGIOLOGREQ *PVDDBGIOLOGREQ;
/**
* I/O log event types.
*/
typedef enum VDIOLOGEVENT
{
/** Invalid event. */
VDIOLOGEVENT_INVALID = 0,
/** I/O request start event. */
/** I/O request complete event. */
/** No more events logged. */
/** 32bit type blowup. */
VDIOLOGEVENT_32BIT_HACK = 0x7fffffff
} VDIOLOGEVENT;
/** Pointer to an I/O log event. */
typedef VDIOLOGEVENT *PVDIOLOGEVENT;
/**
* Creates a new I/O logger for writing to the I/O log.
*
* @returns VBox status code.
* @param phIoLogger Where to store the I/O logger handle on success.
* @param pszFilename The file to log into.
* @param fFlags Flags for the I/O logger.
*/
VBOXDDU_DECL(int) VDDbgIoLogCreate(PVDIOLOGGER phIoLogger, const char *pszFilename, uint32_t fFlags);
/**
* Opens an existing I/O log and creates a new I/O logger from it.
*
* @returns VBox status code.
* @param phIoLogger Where to store the I/O logger handle on success.
* @param pszFilename The I/O log to use.
*/
/**
* Destroys the given I/O logger handle.
*
* @returns nothing.
* @param hIoLogger The I/O logger handle to destroy.
*/
/**
* Commit all log entries to the log file.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to flush.
*/
/**
* Returns the flags of the given I/O logger.
*
* @returns Flags of the I/O logger.
* @param hIoLogger The I/O logger to use.
*/
/**
* Starts logging of an I/O request.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to use.
* @param fAsync Flag whether the request is synchronous or asynchronous.
* @param enmTxDir The transfer direction to log.
* @param off The start offset of the I/O request to log.
* @param cbIo The number of bytes the I/O request transfered.
* @param pSgBuf The data the I/O request is writing if it is a write request.
* Can be NULL if the logger is instructed to not log the data
* or a flush request is logged.
* @param phIoLogEntry Where to store the I/O log entry handle on success.
*/
VBOXDDU_DECL(int) VDDbgIoLogStart(VDIOLOGGER hIoLogger, bool fAsync, VDDBGIOLOGREQ enmTxDir, uint64_t off, size_t cbIo, PCRTSGBUF pSgBuf,
/**
* Starts logging of a discard request.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to use.
* @param fAsync Flag whether the request is synchronous or asynchronous.
* @param paRanges The array of ranges to discard.
* @param cRanges Number of rnages in the array.
* @param phIoLogEntry Where to store the I/O log entry handle on success.
*/
VBOXDDU_DECL(int) VDDbgIoLogStartDiscard(VDIOLOGGER hIoLogger, bool fAsync, PCRTRANGE paRanges, unsigned cRanges,
/**
* Marks the given I/O log entry as completed.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to use.
* @param hIoLogEntry The I/O log entry to complete.
* @param rcReq The status code the request completed with.
* @param pSgBuf The data read if the request was a read and it succeeded.
*/
VBOXDDU_DECL(int) VDDbgIoLogComplete(VDIOLOGGER hIoLogger, VDIOLOGENT hIoLogEntry, int rcReq, PCRTSGBUF pSgBuf);
/**
* Gets the next event type from the I/O log.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to use.
* @param penmEvent Where to store the next event on success.
*/
/**
* Gets the next request type from the I/O log.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to use.
* @param penmEvent Where to store the next event on success.
*/
/**
* Returns the start event from the I/O log.
*
* @returns VBox status code.
* @retval VERR_EOF if the end of the log is reached.
* @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
* pcbIo will hold the required buffer size on return.
* @param hIoLogger The I/O logger to use.
* @param pidEvent The ID of the event to identify the corresponding complete event.
* @param pfAsync Where to store the flag whether the request is
* @param poff Where to store the offset of the next I/O log entry on success.
* @param pcbIo Where to store the transfer size of the next I/O log entry on success.
* @param cbBuf Size of the provided data buffer.
* @param pvBuf Where to store the data of the next I/O log entry on success.
*/
/**
* Returns the discard start event from the I/O log.
*
* @returns VBox status code.
* @retval VERR_EOF if the end of the log is reached.
* @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
* pcbIo will hold the required buffer size on return.
* @param hIoLogger The I/O logger to use.
* @param pidEvent The ID of the event to identify the corresponding complete event.
* @param pfAsync Where to store the flag whether the request is
* @param ppaRanges Where to store the pointer to the range array on success.
* @param pcRanges Where to store the number of entries in the array on success.
*/
VBOXDDU_DECL(int) VDDbgIoLogEventGetStartDiscard(VDIOLOGGER hIoLogger, uint64_t *pidEvent, bool *pfAsync,
/**
* Returns the complete from the I/O log.
*
* @returns VBox status code.
* @retval VERR_EOF if the end of the log is reached
* @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
* pcbIo will hold the required buffer size on return.
* @param hIoLogger The I/O logger to use.
* @param pidEvent The ID of the event to identify the corresponding start event.
* @param pRc Where to store the status code of the request on success.
* @param pmsDuration Where to store the duration of the request.
* @param pcbIo Where to store the transfer size of the next I/O log entry on success.
* @param cbBuf Size of the provided data buffer.
* @param pvBuf Where to store the data of the data transfered during a read request.
*/
/** @} */
#endif