VirtualBox

source: vbox/trunk/include/VBox/vddbg.h@ 44399

Last change on this file since 44399 was 38876, checked in by vboxsync, 13 years ago

Storage: Add async discard API

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.8 KB
Line 
1/** @file
2 * VD Debug API.
3 */
4
5/*
6 * Copyright (C) 2011 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___VBox_VDDbg_h
27#define ___VBox_VDDbg_h
28
29#include <VBox/cdefs.h>
30#include <VBox/types.h>
31#include <VBox/err.h>
32#include <VBox/vd.h> /* for VDRANGE */
33#include <iprt/sg.h>
34
35RT_C_DECLS_BEGIN
36
37#ifdef IN_RING0
38# error "There are no VD Debug APIs available in Ring-0 Host Context!"
39#endif
40
41/** @defgroup grp_vddbg VD Debug API
42 * @{
43 */
44
45/** I/O logger handle. */
46typedef struct VDIOLOGGERINT *VDIOLOGGER;
47/** Pointer to an I/O logger handler. */
48typedef VDIOLOGGER *PVDIOLOGGER;
49
50/** Pointer to an I/O log entry handle. */
51typedef struct VDIOLOGENTINT *VDIOLOGENT;
52/** Pointer to an I/O log entry handle. */
53typedef VDIOLOGENT *PVDIOLOGENT;
54
55/** I/O logger buffers all log entries in memory until VDDbgIoLogCommit() is called.
56 * If not given all entries are immediately logged to the file. */
57#define VDDBG_IOLOG_MEMORY_BUFFER RT_BIT_32(0)
58/** I/O logger logs the written data. */
59#define VDDBG_IOLOG_LOG_DATA_WRITTEN RT_BIT_32(1)
60/** I/O logger logs the read data. */
61#define VDDBG_IOLOG_LOG_DATA_READ RT_BIT_32(2)
62/** I/O logger logs all data. */
63#define VDDBG_IOLOG_LOG_DATA (VDDBG_IOLOG_LOG_DATA_READ | VDDBG_IOLOG_LOG_DATA_WRITTEN)
64/** Mask of valid flags. */
65#define VDDBG_IOLOG_VALID_MASK (VDDBG_IOLOG_MEMORY_BUFFER | VDDBG_IOLOG_LOG_DATA)
66
67/**
68 * I/O direction.
69 */
70typedef enum VDDBGIOLOGREQ
71{
72 /** Invalid direction. */
73 VDDBGIOLOGREQ_INVALID = 0,
74 /** Read. */
75 VDDBGIOLOGREQ_READ,
76 /** Write. */
77 VDDBGIOLOGREQ_WRITE,
78 /** Flush. */
79 VDDBGIOLOGREQ_FLUSH,
80 /** Discard. */
81 VDDBGIOLOGREQ_DISCARD,
82 /** 32bit hack. */
83 VDDBGIOLOGREQ_32BIT_HACK = 0x7fffffff
84} VDDBGIOLOGREQ;
85/** Pointer to a I/O direction. */
86typedef VDDBGIOLOGREQ *PVDDBGIOLOGREQ;
87
88/**
89 * I/O log event types.
90 */
91typedef enum VDIOLOGEVENT
92{
93 /** Invalid event. */
94 VDIOLOGEVENT_INVALID = 0,
95 /** I/O request start event. */
96 VDIOLOGEVENT_START,
97 /** I/O request complete event. */
98 VDIOLOGEVENT_COMPLETE,
99 /** No more events logged. */
100 VDIOLOGEVENT_END,
101 /** 32bit type blowup. */
102 VDIOLOGEVENT_32BIT_HACK = 0x7fffffff
103} VDIOLOGEVENT;
104/** Pointer to an I/O log event. */
105typedef VDIOLOGEVENT *PVDIOLOGEVENT;
106
107/**
108 * Creates a new I/O logger for writing to the I/O log.
109 *
110 * @returns VBox status code.
111 * @param phIoLogger Where to store the I/O logger handle on success.
112 * @param pszFilename The file to log into.
113 * @param fFlags Flags for the I/O logger.
114 */
115VBOXDDU_DECL(int) VDDbgIoLogCreate(PVDIOLOGGER phIoLogger, const char *pszFilename, uint32_t fFlags);
116
117/**
118 * Opens an existing I/O log and creates a new I/O logger from it.
119 *
120 * @returns VBox status code.
121 * @param phIoLogger Where to store the I/O logger handle on success.
122 * @param pszFilename The I/O log to use.
123 */
124VBOXDDU_DECL(int) VDDbgIoLogOpen(PVDIOLOGGER phIoLogger, const char *pszFilename);
125
126/**
127 * Destroys the given I/O logger handle.
128 *
129 * @returns nothing.
130 * @param hIoLogger The I/O logger handle to destroy.
131 */
132VBOXDDU_DECL(void) VDDbgIoLogDestroy(VDIOLOGGER hIoLogger);
133
134/**
135 * Commit all log entries to the log file.
136 *
137 * @returns VBox status code.
138 * @param hIoLogger The I/O logger to flush.
139 */
140VBOXDDU_DECL(int) VDDbgIoLogCommit(VDIOLOGGER hIoLogger);
141
142/**
143 * Returns the flags of the given I/O logger.
144 *
145 * @returns Flags of the I/O logger.
146 * @param hIoLogger The I/O logger to use.
147 */
148VBOXDDU_DECL(uint32_t) VDDbgIoLogGetFlags(VDIOLOGGER hIoLogger);
149
150/**
151 * Starts logging of an I/O request.
152 *
153 * @returns VBox status code.
154 * @param hIoLogger The I/O logger to use.
155 * @param fAsync Flag whether the request is synchronous or asynchronous.
156 * @param enmTxDir The transfer direction to log.
157 * @param off The start offset of the I/O request to log.
158 * @param cbIo The number of bytes the I/O request transfered.
159 * @param pSgBuf The data the I/O request is writing if it is a write request.
160 * Can be NULL if the logger is instructed to not log the data
161 * or a flush request is logged.
162 * @param phIoLogEntry Where to store the I/O log entry handle on success.
163 */
164VBOXDDU_DECL(int) VDDbgIoLogStart(VDIOLOGGER hIoLogger, bool fAsync, VDDBGIOLOGREQ enmTxDir, uint64_t off, size_t cbIo, PCRTSGBUF pSgBuf,
165 PVDIOLOGENT phIoLogEntry);
166
167/**
168 * Starts logging of a discard request.
169 *
170 * @returns VBox status code.
171 * @param hIoLogger The I/O logger to use.
172 * @param fAsync Flag whether the request is synchronous or asynchronous.
173 * @param paRanges The array of ranges to discard.
174 * @param cRanges Number of rnages in the array.
175 * @param phIoLogEntry Where to store the I/O log entry handle on success.
176 */
177VBOXDDU_DECL(int) VDDbgIoLogStartDiscard(VDIOLOGGER hIoLogger, bool fAsync, PCRTRANGE paRanges, unsigned cRanges,
178 PVDIOLOGENT phIoLogEntry);
179
180/**
181 * Marks the given I/O log entry as completed.
182 *
183 * @returns VBox status code.
184 * @param hIoLogger The I/O logger to use.
185 * @param hIoLogEntry The I/O log entry to complete.
186 * @param rcReq The status code the request completed with.
187 * @param pSgBuf The data read if the request was a read and it succeeded.
188 */
189VBOXDDU_DECL(int) VDDbgIoLogComplete(VDIOLOGGER hIoLogger, VDIOLOGENT hIoLogEntry, int rcReq, PCRTSGBUF pSgBuf);
190
191/**
192 * Gets the next event type from the I/O log.
193 *
194 * @returns VBox status code.
195 * @param hIoLogger The I/O logger to use.
196 * @param penmEvent Where to store the next event on success.
197 */
198VBOXDDU_DECL(int) VDDbgIoLogEventTypeGetNext(VDIOLOGGER hIoLogger, VDIOLOGEVENT *penmEvent);
199
200/**
201 * Gets the next request type from the I/O log.
202 *
203 * @returns VBox status code.
204 * @param hIoLogger The I/O logger to use.
205 * @param penmEvent Where to store the next event on success.
206 */
207VBOXDDU_DECL(int) VDDbgIoLogReqTypeGetNext(VDIOLOGGER hIoLogger, PVDDBGIOLOGREQ penmReq);
208
209/**
210 * Returns the start event from the I/O log.
211 *
212 * @returns VBox status code.
213 * @retval VERR_EOF if the end of the log is reached.
214 * @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
215 * pcbIo will hold the required buffer size on return.
216 * @param hIoLogger The I/O logger to use.
217 * @param pidEvent The ID of the event to identify the corresponding complete event.
218 * @param pfAsync Where to store the flag whether the request is
219 * @param poff Where to store the offset of the next I/O log entry on success.
220 * @param pcbIo Where to store the transfer size of the next I/O log entry on success.
221 * @param cbBuf Size of the provided data buffer.
222 * @param pvBuf Where to store the data of the next I/O log entry on success.
223 */
224VBOXDDU_DECL(int) VDDbgIoLogEventGetStart(VDIOLOGGER hIoLogger, uint64_t *pidEvent, bool *pfAsync,
225 uint64_t *poff, size_t *pcbIo, size_t cbBuf, void *pvBuf);
226
227/**
228 * Returns the discard start event from the I/O log.
229 *
230 * @returns VBox status code.
231 * @retval VERR_EOF if the end of the log is reached.
232 * @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
233 * pcbIo will hold the required buffer size on return.
234 * @param hIoLogger The I/O logger to use.
235 * @param pidEvent The ID of the event to identify the corresponding complete event.
236 * @param pfAsync Where to store the flag whether the request is
237 * @param ppaRanges Where to store the pointer to the range array on success.
238 * @param pcRanges Where to store the number of entries in the array on success.
239 */
240VBOXDDU_DECL(int) VDDbgIoLogEventGetStartDiscard(VDIOLOGGER hIoLogger, uint64_t *pidEvent, bool *pfAsync,
241 PRTRANGE *ppaRanges, unsigned *pcRanges);
242
243/**
244 * Returns the complete from the I/O log.
245 *
246 * @returns VBox status code.
247 * @retval VERR_EOF if the end of the log is reached
248 * @retval VERR_BUFFER_OVERFLOW if the provided data buffer can't hold the data.
249 * pcbIo will hold the required buffer size on return.
250 * @param hIoLogger The I/O logger to use.
251 * @param pidEvent The ID of the event to identify the corresponding start event.
252 * @param pRc Where to store the status code of the request on success.
253 * @param pmsDuration Where to store the duration of the request.
254 * @param pcbIo Where to store the transfer size of the next I/O log entry on success.
255 * @param cbBuf Size of the provided data buffer.
256 * @param pvBuf Where to store the data of the data transfered during a read request.
257 */
258VBOXDDU_DECL(int) VDDbgIoLogEventGetComplete(VDIOLOGGER hIoLogger, uint64_t *pidEvent, int *pRc,
259 uint64_t *pmsDuration, size_t *pcbIo, size_t cbBuf, void *pvBuf);
260
261/** @} */
262
263RT_C_DECLS_END
264
265#endif
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette