1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
/** @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;
* you can redistribute it and/or modify it under the terms of the GNU
* 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
#include <VBox/cdefs.h>
#include <VBox/types.h>
#include <VBox/err.h>
#include <VBox/vd.h> /* for VDRANGE */
#include <iprt/sg.h>
RT_C_DECLS_BEGIN
#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. */
#define VDDBG_IOLOG_LOG_DATA_WRITTEN RT_BIT_32(1)
/** I/O logger logs the read data. */
#define VDDBG_IOLOG_LOG_DATA_READ RT_BIT_32(2)
/** I/O logger logs all data. */
#define VDDBG_IOLOG_LOG_DATA (VDDBG_IOLOG_LOG_DATA_READ | VDDBG_IOLOG_LOG_DATA_WRITTEN)
/** Mask of valid flags. */
#define VDDBG_IOLOG_VALID_MASK (VDDBG_IOLOG_MEMORY_BUFFER | VDDBG_IOLOG_LOG_DATA)
/**
* I/O direction.
*/
typedef enum VDDBGIOLOGREQ
{
/** Invalid direction. */
VDDBGIOLOGREQ_INVALID = 0,
/** Read. */
VDDBGIOLOGREQ_READ,
/** Write. */
VDDBGIOLOGREQ_WRITE,
/** Flush. */
VDDBGIOLOGREQ_FLUSH,
/** Discard. */
VDDBGIOLOGREQ_DISCARD,
/** 32bit hack. */
VDDBGIOLOGREQ_32BIT_HACK = 0x7fffffff
} VDDBGIOLOGREQ;
/** 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. */
VDIOLOGEVENT_START,
/** I/O request complete event. */
VDIOLOGEVENT_COMPLETE,
/** No more events logged. */
VDIOLOGEVENT_END,
/** 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.
*/
VBOXDDU_DECL(int) VDDbgIoLogOpen(PVDIOLOGGER phIoLogger, const char *pszFilename);
/**
* Destroys the given I/O logger handle.
*
* @returns nothing.
* @param hIoLogger The I/O logger handle to destroy.
*/
VBOXDDU_DECL(void) VDDbgIoLogDestroy(VDIOLOGGER hIoLogger);
/**
* Commit all log entries to the log file.
*
* @returns VBox status code.
* @param hIoLogger The I/O logger to flush.
*/
VBOXDDU_DECL(int) VDDbgIoLogCommit(VDIOLOGGER hIoLogger);
/**
* Returns the flags of the given I/O logger.
*
* @returns Flags of the I/O logger.
* @param hIoLogger The I/O logger to use.
*/
VBOXDDU_DECL(uint32_t) VDDbgIoLogGetFlags(VDIOLOGGER hIoLogger);
/**
* 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,
PVDIOLOGENT phIoLogEntry);
/**
* 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,
PVDIOLOGENT phIoLogEntry);
/**
* 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.
*/
VBOXDDU_DECL(int) VDDbgIoLogEventTypeGetNext(VDIOLOGGER hIoLogger, VDIOLOGEVENT *penmEvent);
/**
* 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.
*/
VBOXDDU_DECL(int) VDDbgIoLogReqTypeGetNext(VDIOLOGGER hIoLogger, PVDDBGIOLOGREQ penmReq);
/**
* 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.
*/
VBOXDDU_DECL(int) VDDbgIoLogEventGetStart(VDIOLOGGER hIoLogger, uint64_t *pidEvent, bool *pfAsync,
uint64_t *poff, size_t *pcbIo, size_t cbBuf, void *pvBuf);
/**
* 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,
PRTRANGE *ppaRanges, unsigned *pcRanges);
/**
* 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.
*/
VBOXDDU_DECL(int) VDDbgIoLogEventGetComplete(VDIOLOGGER hIoLogger, uint64_t *pidEvent, int *pRc,
uint64_t *pmsDuration, size_t *pcbIo, size_t cbBuf, void *pvBuf);
/** @} */
RT_C_DECLS_END
#endif
|
