pdmstorageifs.h@ 59539

Last change on this file since 59539 was 59539, checked in by vboxsync, 9 years ago
Storage/DrvVD: Add methods to PDMIMEDIAEX for saving the request state of suspended requests. Required for making saving/restoring the VM state work when the user saved a VM state after it got suspended due to a recoverable I/O error
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 43.0 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, Storage related interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2016 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_vmm_pdmstorageifs_h
27	#define ___VBox_vmm_pdmstorageifs_h
28
29	#include <iprt/sg.h>
30	#include <VBox/types.h>
31
32	RT_C_DECLS_BEGIN
33
34	/** @defgroup grp_pdm_ifs_storage PDM Storage Interfaces
35	* @ingroup grp_pdm_interfaces
36	* @{
37	*/
38
39
40	/** Pointer to a mount interface. */
41	typedef struct PDMIMOUNTNOTIFY *PPDMIMOUNTNOTIFY;
42	/**
43	* Block interface (up).
44	* Pair with PDMIMOUNT.
45	*/
46	typedef struct PDMIMOUNTNOTIFY
47	{
48	/**
49	* Called when a media is mounted.
50	*
51	* @param pInterface Pointer to the interface structure containing the called function pointer.
52	* @thread The emulation thread.
53	*/
54	DECLR3CALLBACKMEMBER(void, pfnMountNotify,(PPDMIMOUNTNOTIFY pInterface));
55
56	/**
57	* Called when a media is unmounted
58	* @param pInterface Pointer to the interface structure containing the called function pointer.
59	* @thread The emulation thread.
60	*/
61	DECLR3CALLBACKMEMBER(void, pfnUnmountNotify,(PPDMIMOUNTNOTIFY pInterface));
62	} PDMIMOUNTNOTIFY;
63	/** PDMIMOUNTNOTIFY interface ID. */
64	#define PDMIMOUNTNOTIFY_IID "fa143ac9-9fc6-498e-997f-945380a558f9"
65
66
67	/** Pointer to mount interface. */
68	typedef struct PDMIMOUNT *PPDMIMOUNT;
69	/**
70	* Mount interface (down).
71	* Pair with PDMIMOUNTNOTIFY.
72	*/
73	typedef struct PDMIMOUNT
74	{
75	/**
76	* Unmount the media.
77	*
78	* The driver will validate and pass it on. On the rebounce it will decide whether or not to detach it self.
79	*
80	* @returns VBox status code.
81	* @param pInterface Pointer to the interface structure containing the called function pointer.
82	* @thread The emulation thread.
83	* @param fForce Force the unmount, even for locked media.
84	* @param fEject Eject the medium. Only relevant for host drives.
85	* @thread The emulation thread.
86	*/
87	DECLR3CALLBACKMEMBER(int, pfnUnmount,(PPDMIMOUNT pInterface, bool fForce, bool fEject));
88
89	/**
90	* Checks if a media is mounted.
91	*
92	* @returns true if mounted.
93	* @returns false if not mounted.
94	* @param pInterface Pointer to the interface structure containing the called function pointer.
95	* @thread Any thread.
96	*/
97	DECLR3CALLBACKMEMBER(bool, pfnIsMounted,(PPDMIMOUNT pInterface));
98
99	/**
100	* Locks the media, preventing any unmounting of it.
101	*
102	* @returns VBox status code.
103	* @param pInterface Pointer to the interface structure containing the called function pointer.
104	* @thread The emulation thread.
105	*/
106	DECLR3CALLBACKMEMBER(int, pfnLock,(PPDMIMOUNT pInterface));
107
108	/**
109	* Unlocks the media, canceling previous calls to pfnLock().
110	*
111	* @returns VBox status code.
112	* @param pInterface Pointer to the interface structure containing the called function pointer.
113	* @thread The emulation thread.
114	*/
115	DECLR3CALLBACKMEMBER(int, pfnUnlock,(PPDMIMOUNT pInterface));
116
117	/**
118	* Checks if a media is locked.
119	*
120	* @returns true if locked.
121	* @returns false if not locked.
122	* @param pInterface Pointer to the interface structure containing the called function pointer.
123	* @thread Any thread.
124	*/
125	DECLR3CALLBACKMEMBER(bool, pfnIsLocked,(PPDMIMOUNT pInterface));
126	} PDMIMOUNT;
127	/** PDMIMOUNT interface ID. */
128	#define PDMIMOUNT_IID "34fc7a4c-623a-4806-a6bf-5be1be33c99f"
129
130
131	/**
132	* Callback which provides progress information.
133	*
134	* @return VBox status code.
135	* @param pvUser Opaque user data.
136	* @param uPercent Completion percentage.
137	*/
138	typedef DECLCALLBACK(int) FNSIMPLEPROGRESS(void *pvUser, unsigned uPercentage);
139	/** Pointer to FNSIMPLEPROGRESS() */
140	typedef FNSIMPLEPROGRESS *PFNSIMPLEPROGRESS;
141
142
143	/**
144	* Media type.
145	*/
146	typedef enum PDMMEDIATYPE
147	{
148	/** Error (for the query function). */
149	PDMMEDIATYPE_ERROR = 1,
150	/** 360KB 5 1/4" floppy drive. */
151	PDMMEDIATYPE_FLOPPY_360,
152	/** 720KB 3 1/2" floppy drive. */
153	PDMMEDIATYPE_FLOPPY_720,
154	/** 1.2MB 5 1/4" floppy drive. */
155	PDMMEDIATYPE_FLOPPY_1_20,
156	/** 1.44MB 3 1/2" floppy drive. */
157	PDMMEDIATYPE_FLOPPY_1_44,
158	/** 2.88MB 3 1/2" floppy drive. */
159	PDMMEDIATYPE_FLOPPY_2_88,
160	/** Fake drive that can take up to 15.6 MB images.
161	* C=255, H=2, S=63. */
162	PDMMEDIATYPE_FLOPPY_FAKE_15_6,
163	/** Fake drive that can take up to 63.5 MB images.
164	* C=255, H=2, S=255. */
165	PDMMEDIATYPE_FLOPPY_FAKE_63_5,
166	/** CDROM drive. */
167	PDMMEDIATYPE_CDROM,
168	/** DVD drive. */
169	PDMMEDIATYPE_DVD,
170	/** Hard disk drive. */
171	PDMMEDIATYPE_HARD_DISK
172	} PDMMEDIATYPE;
173
174	/** Check if the given block type is a floppy. */
175	#define PDMMEDIATYPE_IS_FLOPPY(a_enmType) ( (a_enmType) >= PDMMEDIATYPE_FLOPPY_360 && (a_enmType) <= PDMMEDIATYPE_FLOPPY_2_88 )
176
177	/**
178	* Raw command data transfer direction.
179	*/
180	typedef enum PDMMEDIATXDIR
181	{
182	PDMMEDIATXDIR_NONE = 0,
183	PDMMEDIATXDIR_FROM_DEVICE,
184	PDMMEDIATXDIR_TO_DEVICE
185	} PDMMEDIATXDIR;
186
187	/**
188	* Media geometry structure.
189	*/
190	typedef struct PDMMEDIAGEOMETRY
191	{
192	/** Number of cylinders. */
193	uint32_t cCylinders;
194	/** Number of heads. */
195	uint32_t cHeads;
196	/** Number of sectors. */
197	uint32_t cSectors;
198	} PDMMEDIAGEOMETRY;
199
200	/** Pointer to media geometry structure. */
201	typedef PDMMEDIAGEOMETRY *PPDMMEDIAGEOMETRY;
202	/** Pointer to constant media geometry structure. */
203	typedef const PDMMEDIAGEOMETRY *PCPDMMEDIAGEOMETRY;
204
205	/** Pointer to a media port interface. */
206	typedef struct PDMIMEDIAPORT *PPDMIMEDIAPORT;
207	/**
208	* Media port interface (down).
209	*/
210	typedef struct PDMIMEDIAPORT
211	{
212	/**
213	* Returns the storage controller name, instance and LUN of the attached medium.
214	*
215	* @returns VBox status.
216	* @param pInterface Pointer to this interface.
217	* @param ppcszController Where to store the name of the storage controller.
218	* @param piInstance Where to store the instance number of the controller.
219	* @param piLUN Where to store the LUN of the attached device.
220	*/
221	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMIMEDIAPORT pInterface, const char **ppcszController,
222	uint32_t piInstance, uint32_t piLUN));
223
224	} PDMIMEDIAPORT;
225	/** PDMIMEDIAPORT interface ID. */
226	#define PDMIMEDIAPORT_IID "9f7e8c9e-6d35-4453-bbef-1f78033174d6"
227
228	/** Pointer to a media interface. */
229	typedef struct PDMIMEDIA *PPDMIMEDIA;
230	/**
231	* Media interface (up).
232	* Pairs with PDMIMEDIAPORT.
233	*/
234	typedef struct PDMIMEDIA
235	{
236	/**
237	* Read bits.
238	*
239	* @returns VBox status code.
240	* @param pInterface Pointer to the interface structure containing the called function pointer.
241	* @param off Offset to start reading from. The offset must be aligned to a sector boundary.
242	* @param pvBuf Where to store the read bits.
243	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
244	* @thread Any thread.
245	*/
246	DECLR3CALLBACKMEMBER(int, pfnRead,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
247
248	/**
249	* Read bits - version for DevPcBios.
250	*
251	* @returns VBox status code.
252	* @param pInterface Pointer to the interface structure containing the called function pointer.
253	* @param off Offset to start reading from. The offset must be aligned to a sector boundary.
254	* @param pvBuf Where to store the read bits.
255	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
256	* @thread Any thread.
257	*
258	* @note: Special version of pfnRead which doesn't try to suspend the VM when the DEKs for encrypted disks
259	* are missing but just returns an error.
260	*/
261	DECLR3CALLBACKMEMBER(int, pfnReadPcBios,(PPDMIMEDIA pInterface, uint64_t off, void *pvBuf, size_t cbRead));
262
263	/**
264	* Write bits.
265	*
266	* @returns VBox status code.
267	* @param pInterface Pointer to the interface structure containing the called function pointer.
268	* @param off Offset to start writing at. The offset must be aligned to a sector boundary.
269	* @param pvBuf Where to store the write bits.
270	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
271	* @thread Any thread.
272	*/
273	DECLR3CALLBACKMEMBER(int, pfnWrite,(PPDMIMEDIA pInterface, uint64_t off, const void *pvBuf, size_t cbWrite));
274
275	/**
276	* Make sure that the bits written are actually on the storage medium.
277	*
278	* @returns VBox status code.
279	* @param pInterface Pointer to the interface structure containing the called function pointer.
280	* @thread Any thread.
281	*/
282	DECLR3CALLBACKMEMBER(int, pfnFlush,(PPDMIMEDIA pInterface));
283
284	/**
285	* Send a raw command to the underlying device (CDROM).
286	* This method is optional (i.e. the function pointer may be NULL).
287	*
288	* @returns VBox status code.
289	* @param pInterface Pointer to the interface structure containing the called function pointer.
290	* @param pbCmd Offset to start reading from.
291	* @param enmTxDir Direction of transfer.
292	* @param pvBuf Pointer tp the transfer buffer.
293	* @param cbBuf Size of the transfer buffer.
294	* @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
295	* @param cTimeoutMillies Command timeout in milliseconds.
296	* @thread Any thread.
297	*/
298	DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIMEDIA pInterface, const uint8_t pbCmd, PDMMEDIATXDIR enmTxDir, void pvBuf, uint32_t pcbBuf, uint8_t pabSense, size_t cbSense, uint32_t cTimeoutMillies));
299
300	/**
301	* Merge medium contents during a live snapshot deletion. All details
302	* must have been configured through CFGM or this will fail.
303	* This method is optional (i.e. the function pointer may be NULL).
304	*
305	* @returns VBox status code.
306	* @param pInterface Pointer to the interface structure containing the called function pointer.
307	* @param pfnProgress Function pointer for progress notification.
308	* @param pvUser Opaque user data for progress notification.
309	* @thread Any thread.
310	*/
311	DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIMEDIA pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
312
313	/**
314	* Sets the secret key retrieval interface to use to get secret keys.
315	*
316	* @returns VBox status code.
317	* @param pInterface Pointer to the interface structure containing the called function pointer.
318	* @param pIfSecKey The secret key interface to use.
319	* Use NULL to clear the currently set interface and clear all secret
320	* keys from the user.
321	* @param pIfSecKeyHlp The secret key helper interface to use.
322	* @thread Any thread.
323	*/
324	DECLR3CALLBACKMEMBER(int, pfnSetSecKeyIf,(PPDMIMEDIA pInterface, PPDMISECKEY pIfSecKey,
325	PPDMISECKEYHLP pIfSecKeyHlp));
326
327	/**
328	* Get the media size in bytes.
329	*
330	* @returns Media size in bytes.
331	* @param pInterface Pointer to the interface structure containing the called function pointer.
332	* @thread Any thread.
333	*/
334	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
335
336	/**
337	* Gets the media sector size in bytes.
338	*
339	* @returns Media sector size in bytes.
340	* @param pInterface Pointer to the interface structure containing the called function pointer.
341	* @thread Any thread.
342	*/
343	DECLR3CALLBACKMEMBER(uint32_t, pfnGetSectorSize,(PPDMIMEDIA pInterface));
344
345	/**
346	* Check if the media is readonly or not.
347	*
348	* @returns true if readonly.
349	* @returns false if read/write.
350	* @param pInterface Pointer to the interface structure containing the called function pointer.
351	* @thread Any thread.
352	*/
353	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
354
355	/**
356	* Get stored media geometry (physical CHS, PCHS) - BIOS property.
357	* This is an optional feature of a media.
358	*
359	* @returns VBox status code.
360	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
361	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetPCHSGeometry() yet.
362	* @param pInterface Pointer to the interface structure containing the called function pointer.
363	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
364	* @remark This has no influence on the read/write operations.
365	* @thread Any thread.
366	*/
367	DECLR3CALLBACKMEMBER(int, pfnBiosGetPCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
368
369	/**
370	* Store the media geometry (physical CHS, PCHS) - BIOS property.
371	* This is an optional feature of a media.
372	*
373	* @returns VBox status code.
374	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
375	* @param pInterface Pointer to the interface structure containing the called function pointer.
376	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
377	* @remark This has no influence on the read/write operations.
378	* @thread The emulation thread.
379	*/
380	DECLR3CALLBACKMEMBER(int, pfnBiosSetPCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
381
382	/**
383	* Get stored media geometry (logical CHS, LCHS) - BIOS property.
384	* This is an optional feature of a media.
385	*
386	* @returns VBox status code.
387	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
388	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetLCHSGeometry() yet.
389	* @param pInterface Pointer to the interface structure containing the called function pointer.
390	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
391	* @remark This has no influence on the read/write operations.
392	* @thread Any thread.
393	*/
394	DECLR3CALLBACKMEMBER(int, pfnBiosGetLCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
395
396	/**
397	* Store the media geometry (logical CHS, LCHS) - BIOS property.
398	* This is an optional feature of a media.
399	*
400	* @returns VBox status code.
401	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
402	* @param pInterface Pointer to the interface structure containing the called function pointer.
403	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
404	* @remark This has no influence on the read/write operations.
405	* @thread The emulation thread.
406	*/
407	DECLR3CALLBACKMEMBER(int, pfnBiosSetLCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
408
409	/**
410	* Checks if the device should be visible to the BIOS or not.
411	*
412	* @returns true if the device is visible to the BIOS.
413	* @returns false if the device is not visible to the BIOS.
414	* @param pInterface Pointer to the interface structure containing the called function pointer.
415	* @thread Any thread.
416	*/
417	DECLR3CALLBACKMEMBER(bool, pfnBiosIsVisible,(PPDMIMEDIA pInterface));
418
419	/**
420	* Gets the media type.
421	*
422	* @returns media type.
423	* @param pInterface Pointer to the interface structure containing the called function pointer.
424	* @thread Any thread.
425	*/
426	DECLR3CALLBACKMEMBER(PDMMEDIATYPE, pfnGetType,(PPDMIMEDIA pInterface));
427
428	/**
429	* Gets the UUID of the media drive.
430	*
431	* @returns VBox status code.
432	* @param pInterface Pointer to the interface structure containing the called function pointer.
433	* @param pUuid Where to store the UUID on success.
434	* @thread Any thread.
435	*/
436	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
437
438	/**
439	* Discards the given range.
440	*
441	* @returns VBox status code.
442	* @param pInterface Pointer to the interface structure containing the called function pointer.
443	* @param paRanges Array of ranges to discard.
444	* @param cRanges Number of entries in the array.
445	* @thread Any thread.
446	*/
447	DECLR3CALLBACKMEMBER(int, pfnDiscard,(PPDMIMEDIA pInterface, PCRTRANGE paRanges, unsigned cRanges));
448
449	/**
450	* Allocate buffer memory which is suitable for I/O and might have special proerties for secure
451	* environments (non-pageable memory for sensitive data which should not end up on the disk).
452	*
453	* @returns VBox status code.
454	* @param pInterface Pointer to the interface structure containing the called function pointer.
455	* @param cb Amount of memory to allocate.
456	* @param ppvNew Where to store the pointer to the buffer on success.
457	*/
458	DECLR3CALLBACKMEMBER(int, pfnIoBufAlloc, (PPDMIMEDIA pInterface, size_t cb, void **ppvNew));
459
460	/**
461	* Free memory allocated with PDMIMEDIA::pfnIoBufAlloc().
462	*
463	* @returns VBox status code.
464	* @param pInterface Pointer to the interface structure containing the called function pointer.
465	* @param pv Pointer to the memory to free.
466	* @param cb Amount of bytes given in PDMIMEDIA::pfnIoBufAlloc().
467	*/
468	DECLR3CALLBACKMEMBER(int, pfnIoBufFree, (PPDMIMEDIA pInterface, void *pv, size_t cb));
469
470	} PDMIMEDIA;
471	/** PDMIMEDIA interface ID. */
472	#define PDMIMEDIA_IID "352f2fa2-52c0-4e51-ba3c-9f59b7043218"
473
474
475	/** Pointer to an asynchronous notification interface. */
476	typedef struct PDMIMEDIAASYNCPORT *PPDMIMEDIAASYNCPORT;
477	/**
478	* Asynchronous version of the media interface (up).
479	* Pair with PDMIMEDIAASYNC.
480	*/
481	typedef struct PDMIMEDIAASYNCPORT
482	{
483	/**
484	* Notify completion of a task.
485	*
486	* @returns VBox status code.
487	* @param pInterface Pointer to the interface structure containing the called function pointer.
488	* @param pvUser The user argument given in pfnStartWrite.
489	* @param rcReq IPRT Status code of the completed request.
490	* @thread Any thread.
491	*/
492	DECLR3CALLBACKMEMBER(int, pfnTransferCompleteNotify, (PPDMIMEDIAASYNCPORT pInterface, void *pvUser, int rcReq));
493	} PDMIMEDIAASYNCPORT;
494	/** PDMIMEDIAASYNCPORT interface ID. */
495	#define PDMIMEDIAASYNCPORT_IID "22d38853-901f-4a71-9670-4d9da6e82317"
496
497
498	/** Pointer to an asynchronous media interface. */
499	typedef struct PDMIMEDIAASYNC *PPDMIMEDIAASYNC;
500	/**
501	* Asynchronous version of PDMIMEDIA (down).
502	* Pair with PDMIMEDIAASYNCPORT.
503	*/
504	typedef struct PDMIMEDIAASYNC
505	{
506	/**
507	* Start reading task.
508	*
509	* @returns VBox status code.
510	* @param pInterface Pointer to the interface structure containing the called function pointer.
511	* @param off Offset to start reading from. Must be aligned to a sector boundary.
512	* @param paSegs Pointer to the S/G segment array.
513	* @param cSegs Number of entries in the array.
514	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
515	* @param pvUser User data.
516	* @thread Any thread.
517	*/
518	DECLR3CALLBACKMEMBER(int, pfnStartRead,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbRead, void *pvUser));
519
520	/**
521	* Start writing task.
522	*
523	* @returns VBox status code.
524	* @param pInterface Pointer to the interface structure containing the called function pointer.
525	* @param off Offset to start writing at. Must be aligned to a sector boundary.
526	* @param paSegs Pointer to the S/G segment array.
527	* @param cSegs Number of entries in the array.
528	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
529	* @param pvUser User data.
530	* @thread Any thread.
531	*/
532	DECLR3CALLBACKMEMBER(int, pfnStartWrite,(PPDMIMEDIAASYNC pInterface, uint64_t off, PCRTSGSEG paSegs, unsigned cSegs, size_t cbWrite, void *pvUser));
533
534	/**
535	* Flush everything to disk.
536	*
537	* @returns VBox status code.
538	* @param pInterface Pointer to the interface structure containing the called function pointer.
539	* @param pvUser User argument which is returned in completion callback.
540	* @thread Any thread.
541	*/
542	DECLR3CALLBACKMEMBER(int, pfnStartFlush,(PPDMIMEDIAASYNC pInterface, void *pvUser));
543
544	/**
545	* Discards the given range.
546	*
547	* @returns VBox status code.
548	* @param pInterface Pointer to the interface structure containing the called function pointer.
549	* @param paRanges Array of ranges to discard.
550	* @param cRanges Number of entries in the array.
551	* @param pvUser User argument which is returned in completion callback.
552	* @thread Any thread.
553	*/
554	DECLR3CALLBACKMEMBER(int, pfnStartDiscard,(PPDMIMEDIAASYNC pInterface, PCRTRANGE paRanges, unsigned cRanges, void *pvUser));
555
556	} PDMIMEDIAASYNC;
557	/** PDMIMEDIAASYNC interface ID. */
558	#define PDMIMEDIAASYNC_IID "4be209d3-ccb5-4297-82fe-7d8018bc6ab4"
559
560
561	/**
562	* Opaque I/O request handle.
563	*
564	* The specific content depends on the driver implementing this interface.
565	*/
566	typedef struct PDMMEDIAEXIOREQINT *PDMMEDIAEXIOREQ;
567	/** Pointer to an I/O request handle. */
568	typedef PDMMEDIAEXIOREQ *PPDMMEDIAEXIOREQ;
569
570	/** A I/O request ID. */
571	typedef uint64_t PDMMEDIAEXIOREQID;
572
573	/**
574	* I/O Request Type.
575	*/
576	typedef enum PDMMEDIAEXIOREQTYPE
577	{
578	/** Invalid tpe. */
579	PDMMEDIAEXIOREQTYPE_INVALID = 0,
580	/** Flush request. */
581	PDMMEDIAEXIOREQTYPE_FLUSH,
582	/** Write request. */
583	PDMMEDIAEXIOREQTYPE_WRITE,
584	/** Read request. */
585	PDMMEDIAEXIOREQTYPE_READ,
586	/** Discard request. */
587	PDMMEDIAEXIOREQTYPE_DISCARD
588	} PDMMEDIAEXIOREQTYPE;
589	/** Pointer to a I/O request type. */
590	typedef PDMMEDIAEXIOREQTYPE *PPDMMEDIAEXIOREQTYPE;
591
592	/**
593	* I/O request state.
594	*/
595	typedef enum PDMMEDIAEXIOREQSTATE
596	{
597	/** Invalid state. */
598	PDMMEDIAEXIOREQSTATE_INVALID = 0,
599	/** The request is active and being processed. */
600	PDMMEDIAEXIOREQSTATE_ACTIVE,
601	/** The request is suspended due to an error and no processing will take place. */
602	PDMMEDIAEXIOREQSTATE_SUSPENDED,
603	/** 32bit hack. */
604	PDMMEDIAEXIOREQSTATE_32BIT_HACK = 0x7fffffff
605	} PDMMEDIAEXIOREQSTATE;
606	/** Pointer to a I/O request state. */
607	typedef PDMMEDIAEXIOREQSTATE *PPDMMEDIAEXIOREQSTATE;
608
609	/** @name I/O request specific flags
610	* @{ */
611	/** Default behavior (async I/O).*/
612	#define PDMIMEDIAEX_F_DEFAULT (0)
613	/** The I/O request will be executed synchronously. */
614	#define PDMIMEDIAEX_F_SYNC RT_BIT_32(0)
615	/** Whether to suspend the VM on a recoverable error with
616	* an appropriate error message (disk full, etc.).
617	* The request will be retried by the driver implementing the interface
618	* when the VM resumes the next time. However before suspending the request
619	* the owner of the request will be notified using the PDMMEDIAEXPORT::pfnIoReqStateChanged.
620	* The same goes for resuming the request after the VM was resumed.
621	*/
622	#define PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR RT_BIT_32(1)
623	/** Mask of valid flags. */
624	#define PDMIMEDIAEX_F_VALID (PDMIMEDIAEX_F_SYNC \| PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR)
625	/** @} */
626
627	/** Pointer to an extended media notification interface. */
628	typedef struct PDMIMEDIAEXPORT *PPDMIMEDIAEXPORT;
629
630	/**
631	* Asynchronous version of the media interface (up).
632	* Pair with PDMIMEDIAEXPORT.
633	*/
634	typedef struct PDMIMEDIAEXPORT
635	{
636	/**
637	* Notify completion of a I/O request.
638	*
639	* @returns VBox status code.
640	* @param pInterface Pointer to the interface structure containing the called function pointer.
641	* @param hIoReq The I/O request handle.
642	* @param pvIoReqAlloc The allocator specific memory for this request.
643	* @param rcReq IPRT Status code of the completed request.
644	* VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
645	* PDMIMEDIAEX::pfnIoReqCancel.
646	* @thread Any thread.
647	*/
648	DECLR3CALLBACKMEMBER(int, pfnIoReqCompleteNotify, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
649	void *pvIoReqAlloc, int rcReq));
650
651	/**
652	* Copy data from the memory buffer of the caller to the callees memory buffer for the given request.
653	*
654	* @returns VBox status code.
655	* @retval VERR_PDM_MEDIAEX_IOBUF_OVERFLOW if there is not enough room to store the data.
656	* @param pInterface Pointer to the interface structure containing the called function pointer.
657	* @param hIoReq The I/O request handle.
658	* @param pvIoReqAlloc The allocator specific memory for this request.
659	* @param offDst The destination offset from the start to write the data to.
660	* @param pSgBuf The S/G buffer to read the data from.
661	* @param cbCopy How many bytes to copy.
662	*/
663	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyFromBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
664	void *pvIoReqAlloc, uint32_t offDst, PRTSGBUF pSgBuf,
665	size_t cbCopy));
666
667	/**
668	* Copy data to the memory buffer of the caller from the callees memory buffer for the given request.
669	*
670	* @returns VBox status code.
671	* @retval VERR_PDM_MEDIAEX_IOBUF_UNDERRUN if there is not enough data to copy from the buffer.
672	* @param pInterface Pointer to the interface structure containing the called function pointer.
673	* @param hIoReq The I/O request handle.
674	* @param pvIoReqAlloc The allocator specific memory for this request.
675	* @param offSrc The offset from the start of the buffer to read the data from.
676	* @param pSgBuf The S/G buffer to write the data to.
677	* @param cbCopy How many bytes to copy.
678	*/
679	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyToBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
680	void *pvIoReqAlloc, uint32_t offSrc, PRTSGBUF pSgBuf,
681	size_t cbCopy));
682
683	/**
684	* Notify the request owner about a state change for the request.
685	*
686	* @returns nothing.
687	* @param pInterface Pointer to the interface structure containing the called function pointer.
688	* @param hIoReq The I/O request handle.
689	* @param pvIoReqAlloc The allocator specific memory for this request.
690	* @param enmState The new state of the request.
691	*/
692	DECLR3CALLBACKMEMBER(void, pfnIoReqStateChanged, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
693	void *pvIoReqAlloc, PDMMEDIAEXIOREQSTATE enmState));
694
695	} PDMIMEDIAEXPORT;
696
697	/** PDMIMEDIAAEXPORT interface ID. */
698	#define PDMIMEDIAEXPORT_IID "779f38d0-bcaa-4a49-af2b-6f63edd4181a"
699
700
701	/** Pointer to an extended media interface. */
702	typedef struct PDMIMEDIAEX *PPDMIMEDIAEX;
703
704	/**
705	* Extended version of PDMIMEDIA (down).
706	* Pair with PDMIMEDIAEXPORT.
707	*/
708	typedef struct PDMIMEDIAEX
709	{
710	/**
711	* Sets the size of the allocator specific memory for a I/O request.
712	*
713	* @returns VBox status code.
714	* @param pInterface Pointer to the interface structure containing the called function pointer.
715	* @param cbIoReqAlloc The size of the allocator specific memory in bytes.
716	* @thread EMT.
717	*/
718	DECLR3CALLBACKMEMBER(int, pfnIoReqAllocSizeSet, (PPDMIMEDIAEX pInterface, size_t cbIoReqAlloc));
719
720	/**
721	* Allocates a new I/O request.
722	*
723	* @returns VBox status code.
724	* @retval VERR_PDM_MEDIAEX_IOREQID_CONFLICT if the ID belongs to a still active request.
725	* @param pInterface Pointer to the interface structure containing the called function pointer.
726	* @param phIoReq Where to store the handle to the new I/O request on success.
727	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
728	* NULL if the memory size was not set or set to 0.
729	* @param uIoReqId A custom request ID which can be used to cancel the request.
730	* @param fFlags A combination of PDMIMEDIAEX_F_* flags.
731	* @thread Any thread.
732	*/
733	DECLR3CALLBACKMEMBER(int, pfnIoReqAlloc, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc,
734	PDMMEDIAEXIOREQID uIoReqId, uint32_t fFlags));
735
736	/**
737	* Frees a given I/O request.
738	*
739	* @returns VBox status code.
740	* @retval VERR_PDM_MEDIAEX_IOREQ_INVALID_STATE if the given request is still active.
741	* @param pInterface Pointer to the interface structure containing the called function pointer.
742	* @param hIoReq The I/O request to free.
743	* @thread Any thread.
744	*/
745	DECLR3CALLBACKMEMBER(int, pfnIoReqFree, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
746
747	/**
748	* Cancels a I/O request identified by the ID.
749	*
750	* @returns VBox status code.
751	* @retval VERR_PDM_MEDIAEX_IOREQID_NOT_FOUND if the given ID could not be found in the active request list.
752	* (The request has either completed already or an invalid ID was given).
753	* @param pInterface Pointer to the interface structure containing the called function pointer.
754	* @param uIoReqId The I/O request ID
755	* @thread Any thread.
756	*/
757	DECLR3CALLBACKMEMBER(int, pfnIoReqCancel, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQID uIoReqId));
758
759	/**
760	* Start a reading request.
761	*
762	* @returns VBox status code.
763	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
764	* PDMIMEDIAEX::pfnIoReqCancel.
765	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
766	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
767	* @retval VINF_SUCCESS if the request completed successfully.
768	* @param pInterface Pointer to the interface structure containing the called function pointer.
769	* @param hIoReq The I/O request to associate the read with.
770	* @param off Offset to start reading from. Must be aligned to a sector boundary.
771	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
772	* @thread Any thread.
773	*/
774	DECLR3CALLBACKMEMBER(int, pfnIoReqRead, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbRead));
775
776	/**
777	* Start a writing request.
778	*
779	* @returns VBox status code.
780	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
781	* PDMIMEDIAEX::pfnIoReqCancel.
782	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
783	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
784	* @retval VINF_SUCCESS if the request completed successfully.
785	* @param pInterface Pointer to the interface structure containing the called function pointer.
786	* @param hIoReq The I/O request to associate the write with.
787	* @param off Offset to start reading from. Must be aligned to a sector boundary.
788	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
789	* @thread Any thread.
790	*/
791	DECLR3CALLBACKMEMBER(int, pfnIoReqWrite, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbWrite));
792
793	/**
794	* Flush everything to disk.
795	*
796	* @returns VBox status code.
797	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
798	* PDMIMEDIAEX::pfnIoReqCancel.
799	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
800	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
801	* @retval VINF_SUCCESS if the request completed successfully.
802	* @param pInterface Pointer to the interface structure containing the called function pointer.
803	* @param hIoReq The I/O request to associate the flush with.
804	* @thread Any thread.
805	*/
806	DECLR3CALLBACKMEMBER(int, pfnIoReqFlush, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
807
808	/**
809	* Discards the given range.
810	*
811	* @returns VBox status code.
812	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
813	* PDMIMEDIAEX::pfnIoReqCancel.
814	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
815	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
816	* @retval VINF_SUCCESS if the request completed successfully.
817	* @param pInterface Pointer to the interface structure containing the called function pointer.
818	* @param hIoReq The I/O request to associate the discard with.
819	* @param paRanges Array of ranges to discard.
820	* @param cRanges Number of entries in the array.
821	* @thread Any thread.
822	*/
823	DECLR3CALLBACKMEMBER(int, pfnIoReqDiscard, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, PCRTRANGE paRanges, unsigned cRanges));
824
825	/**
826	* Returns the number of active I/O requests.
827	*
828	* @returns Number of active I/O requests.
829	* @param pInterface Pointer to the interface structure containing the called function pointer.
830	* @thread Any thread.
831	*/
832	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetActiveCount, (PPDMIMEDIAEX pInterface));
833
834	/**
835	* Returns the number of suspended requests.
836	*
837	* @returns Number of suspended I/O requests.
838	* @param pInterface Pointer to the interface structure containing the called function pointer.
839	* @thread Any thread.
840	*/
841	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetSuspendedCount, (PPDMIMEDIAEX pInterface));
842
843	/**
844	* Gets the first suspended request handle.
845	*
846	* @returns VBox status code.
847	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
848	* @param pInterface Pointer to the interface structure containing the called function pointer.
849	* @param phIoReq Where to store the request handle on success.
850	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
851	* @thread Any thread.
852	*
853	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
854	* changes into the active state again. The only purpose for this method for now is to make saving the state
855	* possible without breaking saved state versions.
856	*/
857	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedStart, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc));
858
859	/**
860	* Gets the next suspended request handle.
861	*
862	* @returns VBox status code.
863	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
864	* @param pInterface Pointer to the interface structure containing the called function pointer.
865	* @param hIoReq The current request handle.
866	* @param phIoReqNext Where to store the request handle on success.
867	* @param ppvIoReqAllocNext Where to store the pointer to the allocator specific memory on success.
868	* @thread Any thread.
869	*
870	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
871	* changes into the active state again. The only purpose for this method for now is to make saving the state
872	* possible without breaking saved state versions.
873	*/
874	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedNext, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq,
875	PPDMMEDIAEXIOREQ phIoReqNext, void **ppvIoReqAllocNext));
876
877	/**
878	* Saves the given I/O request state in the provided saved state unit.
879	*
880	* @returns VBox status code.
881	* @param pInterface Pointer to the interface structure containing the called function pointer.
882	* @param pSSM The SSM handle.
883	* @param hIoReq The request handle to save.
884	*/
885	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedSave, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
886
887	/**
888	* Load a suspended request state from the given saved state unit and link it into the suspended list.
889	*
890	* @returns VBox status code.
891	* @param pInterface Pointer to the interface structure containing the called function pointer.
892	* @param pSSM The SSM handle to read the state from.
893	* @param hIoReq The request handle to load the state into.
894	*/
895	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedLoad, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
896
897	} PDMIMEDIAEX;
898	/** PDMIMEDIAEX interface ID. */
899	#define PDMIMEDIAEX_IID "8856ba6a-773b-40ce-92a2-431cd06e678e"
900
901	/**
902	* Data direction.
903	*/
904	typedef enum PDMSCSIREQUESTTXDIR
905	{
906	PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
907	PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
908	PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
909	PDMSCSIREQUESTTXDIR_NONE = 0x03,
910	PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
911	} PDMSCSIREQUESTTXDIR;
912
913	/**
914	* SCSI request structure.
915	*/
916	typedef struct PDMSCSIREQUEST
917	{
918	/** The logical unit. */
919	uint32_t uLogicalUnit;
920	/** Direction of the data flow. */
921	PDMSCSIREQUESTTXDIR uDataDirection;
922	/** Size of the SCSI CDB. */
923	uint32_t cbCDB;
924	/** Pointer to the SCSI CDB. */
925	uint8_t *pbCDB;
926	/** Overall size of all scatter gather list elements
927	* for data transfer if any. */
928	uint32_t cbScatterGather;
929	/** Number of elements in the scatter gather list. */
930	uint32_t cScatterGatherEntries;
931	/** Pointer to the head of the scatter gather list. */
932	PRTSGSEG paScatterGatherHead;
933	/** Size of the sense buffer. */
934	uint32_t cbSenseBuffer;
935	/** Pointer to the sense buffer. *
936	* Current assumption that the sense buffer is not scattered. */
937	uint8_t *pbSenseBuffer;
938	/** Opaque user data for use by the device. Left untouched by everything else! */
939	void *pvUser;
940	} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
941	/** Pointer to a const SCSI request structure. */
942	typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
943
944	/** Pointer to a SCSI port interface. */
945	typedef struct PDMISCSIPORT *PPDMISCSIPORT;
946	/**
947	* SCSI command execution port interface (down).
948	* Pair with PDMISCSICONNECTOR.
949	*/
950	typedef struct PDMISCSIPORT
951	{
952
953	/**
954	* Notify the device on request completion.
955	*
956	* @returns VBox status code.
957	* @param pInterface Pointer to this interface.
958	* @param pSCSIRequest Pointer to the finished SCSI request.
959	* @param rcCompletion SCSI_STATUS_* code for the completed request.
960	* @param fRedo Flag whether the request can to be redone
961	* when it failed.
962	* @param rcReq The status code the request completed with (VERR_*)
963	* Should be only used to choose the correct error message
964	* displayed to the user if the error can be fixed by him
965	* (fRedo is true).
966	*/
967	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest,
968	int rcCompletion, bool fRedo, int rcReq));
969
970	/**
971	* Returns the storage controller name, instance and LUN of the attached medium.
972	*
973	* @returns VBox status.
974	* @param pInterface Pointer to this interface.
975	* @param ppcszController Where to store the name of the storage controller.
976	* @param piInstance Where to store the instance number of the controller.
977	* @param piLUN Where to store the LUN of the attached device.
978	*/
979	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMISCSIPORT pInterface, const char **ppcszController,
980	uint32_t piInstance, uint32_t piLUN));
981
982	} PDMISCSIPORT;
983	/** PDMISCSIPORT interface ID. */
984	#define PDMISCSIPORT_IID "05d9fc3b-e38c-4b30-8344-a323feebcfe5"
985
986	/**
987	* LUN type.
988	*/
989	typedef enum PDMSCSILUNTYPE
990	{
991	PDMSCSILUNTYPE_INVALID = 0,
992	PDMSCSILUNTYPE_SBC, /** Hard disk (SBC) */
993	PDMSCSILUNTYPE_MMC, /** CD/DVD drive (MMC) */
994	PDMSCSILUNTYPE_SSC, /** Tape drive (SSC) */
995	PDMSCSILUNTYPE_32BIT_HACK = 0x7fffffff
996	} PDMSCSILUNTYPE, *PPDMSCSILUNTYPE;
997
998
999	/** Pointer to a SCSI connector interface. */
1000	typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
1001	/**
1002	* SCSI command execution connector interface (up).
1003	* Pair with PDMISCSIPORT.
1004	*/
1005	typedef struct PDMISCSICONNECTOR
1006	{
1007
1008	/**
1009	* Submits a SCSI request for execution.
1010	*
1011	* @returns VBox status code.
1012	* @param pInterface Pointer to this interface.
1013	* @param pSCSIRequest Pointer to the SCSI request to execute.
1014	*/
1015	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
1016
1017	/**
1018	* Queries the type of the attached LUN.
1019	*
1020	* @returns VBox status code.
1021	* @param pInterface Pointer to this interface.
1022	* @param iLUN The logical unit number.
1023	* @param pSCSIRequest Pointer to the LUN to be returned.
1024	*/
1025	DECLR3CALLBACKMEMBER(int, pfnQueryLUNType, (PPDMISCSICONNECTOR pInterface, uint32_t iLun, PPDMSCSILUNTYPE pLUNType));
1026
1027	} PDMISCSICONNECTOR;
1028	/** PDMISCSICONNECTOR interface ID. */
1029	#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
1030
1031	/** @} */
1032
1033	RT_C_DECLS_END
1034
1035	#endif

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/vmm/pdmstorageifs.h@ 59539

Download in other formats: