pdmstorageifs.h@ 88626

Last change on this file since 88626 was 85121, checked in by vboxsync, 4 years ago
iprt/cdefs.h: Refactored the typedef use of DECLCALLBACK as well as DECLCALLBACKMEMBER to wrap the whole expression, similar to the DECLR?CALLBACKMEMBER macros. This allows adding a throw() at the end when compiling with the VC++ compiler to indicate that the callbacks won't throw anything, so we can stop supressing the C5039 warning about passing functions that can potential throw C++ exceptions to extern C code that can't necessarily cope with such (unwind,++). Introduced a few _EX variations that allows specifying different/no calling convention too, as that's handy when dynamically resolving host APIs. Fixed numerous places missing DECLCALLBACK and such. Left two angry @todos regarding use of CreateThread. bugref:9794
Property svn:eol-style set to `native` Property svn:keywords set to `Id Revision`
File size: 47.1 KB

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

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

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

Download in other formats: