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