pdmstorageifs.h@ 63955

Last change on this file since 63955 was 63955, checked in by vboxsync, 8 years ago
pdmstorageifs.h: Small addendum to PDMIMEDIAEX which enables us to replace PDMISCSICONNECTOR with PDMIMEDIAEX later
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 46.5 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	* Data direction for raw SCSI commands.
594	*/
595	typedef enum PDMMEDIAEXIOREQSCSITXDIR
596	{
597	/** Invalid data direction. */
598	PDMMEDIAEXIOREQSCSITXDIR_INVALID = 0,
599	/** Direction is unknown. */
600	PDMMEDIAEXIOREQSCSITXDIR_UNKNOWN,
601	/** Direction is from device to host. */
602	PDMMEDIAEXIOREQSCSITXDIR_FROM_DEVICE,
603	/** Direction is from host to device. */
604	PDMMEDIAEXIOREQSCSITXDIR_TO_DEVICE,
605	/** No data transfer associated with this request. */
606	PDMMEDIAEXIOREQSCSITXDIR_NONE,
607	/** 32bit hack. */
608	PDMMEDIAEXIOREQSCSITXDIR_32BIT_HACK = 0x7fffffff
609	} PDMMEDIAEXIOREQSCSITXDIR;
610
611	/**
612	* I/O request state.
613	*/
614	typedef enum PDMMEDIAEXIOREQSTATE
615	{
616	/** Invalid state. */
617	PDMMEDIAEXIOREQSTATE_INVALID = 0,
618	/** The request is active and being processed. */
619	PDMMEDIAEXIOREQSTATE_ACTIVE,
620	/** The request is suspended due to an error and no processing will take place. */
621	PDMMEDIAEXIOREQSTATE_SUSPENDED,
622	/** 32bit hack. */
623	PDMMEDIAEXIOREQSTATE_32BIT_HACK = 0x7fffffff
624	} PDMMEDIAEXIOREQSTATE;
625	/** Pointer to a I/O request state. */
626	typedef PDMMEDIAEXIOREQSTATE *PPDMMEDIAEXIOREQSTATE;
627
628	/** @name Supported feature flags
629	* @{ */
630	/** I/O requests will execute asynchronously by default. */
631	#define PDMIMEDIAEX_FEATURE_F_ASYNC RT_BIT_32(0)
632	/** The discard request is supported. */
633	#define PDMIMEDIAEX_FEATURE_F_DISCARD RT_BIT_32(1)
634	/** The send raw SCSI command request is supported. */
635	#define PDMIMEDIAEX_FEATURE_F_RAWSCSICMD RT_BIT_32(2)
636	/** Mask of valid flags. */
637	#define PDMIMEDIAEX_FEATURE_F_VALID (PDMIMEDIAEX_FEATURE_F_ASYNC \| PDMIMEDIAEX_FEATURE_F_DISCARD \| PDMIMEDIAEX_FEATURE_F_RAWSCSICMD)
638	/** @} */
639
640	/** @name I/O request specific flags
641	* @{ */
642	/** Default behavior (async I/O).*/
643	#define PDMIMEDIAEX_F_DEFAULT (0)
644	/** The I/O request will be executed synchronously. */
645	#define PDMIMEDIAEX_F_SYNC RT_BIT_32(0)
646	/** Whether to suspend the VM on a recoverable error with
647	* an appropriate error message (disk full, etc.).
648	* The request will be retried by the driver implementing the interface
649	* when the VM resumes the next time. However before suspending the request
650	* the owner of the request will be notified using the PDMMEDIAEXPORT::pfnIoReqStateChanged.
651	* The same goes for resuming the request after the VM was resumed.
652	*/
653	#define PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR RT_BIT_32(1)
654	/** Mask of valid flags. */
655	#define PDMIMEDIAEX_F_VALID (PDMIMEDIAEX_F_SYNC \| PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR)
656	/** @} */
657
658	/** Pointer to an extended media notification interface. */
659	typedef struct PDMIMEDIAEXPORT *PPDMIMEDIAEXPORT;
660
661	/**
662	* Asynchronous version of the media interface (up).
663	* Pair with PDMIMEDIAEXPORT.
664	*/
665	typedef struct PDMIMEDIAEXPORT
666	{
667	/**
668	* Notify completion of a I/O request.
669	*
670	* @returns VBox status code.
671	* @param pInterface Pointer to the interface structure containing the called function pointer.
672	* @param hIoReq The I/O request handle.
673	* @param pvIoReqAlloc The allocator specific memory for this request.
674	* @param rcReq IPRT Status code of the completed request.
675	* VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
676	* PDMIMEDIAEX::pfnIoReqCancel.
677	* @thread Any thread.
678	*/
679	DECLR3CALLBACKMEMBER(int, pfnIoReqCompleteNotify, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
680	void *pvIoReqAlloc, int rcReq));
681
682	/**
683	* Copy data from the memory buffer of the caller to the callees memory buffer for the given request.
684	*
685	* @returns VBox status code.
686	* @retval VERR_PDM_MEDIAEX_IOBUF_OVERFLOW if there is not enough room to store the data.
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 offDst The destination offset from the start to write the data to.
691	* @param pSgBuf The S/G buffer to read the data from.
692	* @param cbCopy How many bytes to copy.
693	*/
694	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyFromBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
695	void *pvIoReqAlloc, uint32_t offDst, PRTSGBUF pSgBuf,
696	size_t cbCopy));
697
698	/**
699	* Copy data to the memory buffer of the caller from the callees memory buffer for the given request.
700	*
701	* @returns VBox status code.
702	* @retval VERR_PDM_MEDIAEX_IOBUF_UNDERRUN if there is not enough data to copy from the buffer.
703	* @param pInterface Pointer to the interface structure containing the called function pointer.
704	* @param hIoReq The I/O request handle.
705	* @param pvIoReqAlloc The allocator specific memory for this request.
706	* @param offSrc The offset from the start of the buffer to read the data from.
707	* @param pSgBuf The S/G buffer to write the data to.
708	* @param cbCopy How many bytes to copy.
709	*/
710	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyToBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
711	void *pvIoReqAlloc, uint32_t offSrc, PRTSGBUF pSgBuf,
712	size_t cbCopy));
713
714	/**
715	* Notify the request owner about a state change for the request.
716	*
717	* @returns nothing.
718	* @param pInterface Pointer to the interface structure containing the called function pointer.
719	* @param hIoReq The I/O request handle.
720	* @param pvIoReqAlloc The allocator specific memory for this request.
721	* @param enmState The new state of the request.
722	*/
723	DECLR3CALLBACKMEMBER(void, pfnIoReqStateChanged, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
724	void *pvIoReqAlloc, PDMMEDIAEXIOREQSTATE enmState));
725
726	} PDMIMEDIAEXPORT;
727
728	/** PDMIMEDIAAEXPORT interface ID. */
729	#define PDMIMEDIAEXPORT_IID "779f38d0-bcaa-4a49-af2b-6f63edd4181a"
730
731
732	/** Pointer to an extended media interface. */
733	typedef struct PDMIMEDIAEX *PPDMIMEDIAEX;
734
735	/**
736	* Extended version of PDMIMEDIA (down).
737	* Pair with PDMIMEDIAEXPORT.
738	*/
739	typedef struct PDMIMEDIAEX
740	{
741	/**
742	* Queries the features supported by the entity implementing this interface.
743	*
744	* @returns VBox status code.
745	* @param pInterface Pointer to the interface structure containing the called function pointer.
746	* @param pfFeatures Where to store the supported feature flags on success.
747	*/
748	DECLR3CALLBACKMEMBER(int, pfnQueryFeatures, (PPDMIMEDIAEX pInterface, uint32_t *pfFeatures));
749
750	/**
751	* Sets the size of the allocator specific memory for a I/O request.
752	*
753	* @returns VBox status code.
754	* @param pInterface Pointer to the interface structure containing the called function pointer.
755	* @param cbIoReqAlloc The size of the allocator specific memory in bytes.
756	* @thread EMT.
757	*/
758	DECLR3CALLBACKMEMBER(int, pfnIoReqAllocSizeSet, (PPDMIMEDIAEX pInterface, size_t cbIoReqAlloc));
759
760	/**
761	* Allocates a new I/O request.
762	*
763	* @returns VBox status code.
764	* @retval VERR_PDM_MEDIAEX_IOREQID_CONFLICT if the ID belongs to a still active request.
765	* @param pInterface Pointer to the interface structure containing the called function pointer.
766	* @param phIoReq Where to store the handle to the new I/O request on success.
767	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
768	* NULL if the memory size was not set or set to 0.
769	* @param uIoReqId A custom request ID which can be used to cancel the request.
770	* @param fFlags A combination of PDMIMEDIAEX_F_* flags.
771	* @thread Any thread.
772	*/
773	DECLR3CALLBACKMEMBER(int, pfnIoReqAlloc, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc,
774	PDMMEDIAEXIOREQID uIoReqId, uint32_t fFlags));
775
776	/**
777	* Frees a given I/O request.
778	*
779	* @returns VBox status code.
780	* @retval VERR_PDM_MEDIAEX_IOREQ_INVALID_STATE if the given request is still active.
781	* @param pInterface Pointer to the interface structure containing the called function pointer.
782	* @param hIoReq The I/O request to free.
783	* @thread Any thread.
784	*/
785	DECLR3CALLBACKMEMBER(int, pfnIoReqFree, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
786
787	/**
788	* Cancels all I/O active requests.
789	*
790	* @returns VBox status code.
791	* @param pInterface Pointer to the interface structure containing the called function pointer.
792	* @thread Any thread.
793	*/
794	DECLR3CALLBACKMEMBER(int, pfnIoReqCancelAll, (PPDMIMEDIAEX pInterface));
795
796	/**
797	* Cancels a I/O request identified by the ID.
798	*
799	* @returns VBox status code.
800	* @retval VERR_PDM_MEDIAEX_IOREQID_NOT_FOUND if the given ID could not be found in the active request list.
801	* (The request has either completed already or an invalid ID was given).
802	* @param pInterface Pointer to the interface structure containing the called function pointer.
803	* @param uIoReqId The I/O request ID
804	* @thread Any thread.
805	*/
806	DECLR3CALLBACKMEMBER(int, pfnIoReqCancel, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQID uIoReqId));
807
808	/**
809	* Start a reading request.
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 read with.
819	* @param off Offset to start reading from. Must be aligned to a sector boundary.
820	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
821	* @thread Any thread.
822	*/
823	DECLR3CALLBACKMEMBER(int, pfnIoReqRead, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbRead));
824
825	/**
826	* Start a writing request.
827	*
828	* @returns VBox status code.
829	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
830	* PDMIMEDIAEX::pfnIoReqCancel.
831	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
832	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
833	* @retval VINF_SUCCESS if the request completed successfully.
834	* @param pInterface Pointer to the interface structure containing the called function pointer.
835	* @param hIoReq The I/O request to associate the write with.
836	* @param off Offset to start reading from. Must be aligned to a sector boundary.
837	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
838	* @thread Any thread.
839	*/
840	DECLR3CALLBACKMEMBER(int, pfnIoReqWrite, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbWrite));
841
842	/**
843	* Flush everything to disk.
844	*
845	* @returns VBox status code.
846	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
847	* PDMIMEDIAEX::pfnIoReqCancel.
848	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
849	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
850	* @retval VINF_SUCCESS if the request completed successfully.
851	* @param pInterface Pointer to the interface structure containing the called function pointer.
852	* @param hIoReq The I/O request to associate the flush with.
853	* @thread Any thread.
854	*/
855	DECLR3CALLBACKMEMBER(int, pfnIoReqFlush, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
856
857	/**
858	* Discards the given range.
859	*
860	* @returns VBox status code.
861	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
862	* PDMIMEDIAEX::pfnIoReqCancel.
863	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
864	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
865	* @retval VINF_SUCCESS if the request completed successfully.
866	* @param pInterface Pointer to the interface structure containing the called function pointer.
867	* @param hIoReq The I/O request to associate the discard with.
868	* @param paRanges Array of ranges to discard.
869	* @param cRanges Number of entries in the array.
870	* @thread Any thread.
871	*/
872	DECLR3CALLBACKMEMBER(int, pfnIoReqDiscard, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, PCRTRANGE paRanges, unsigned cRanges));
873
874	/**
875	* Send a raw command to the underlying device (CDROM).
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	* @param pInterface Pointer to the interface structure containing the called function pointer.
883	* @param hIoReq The I/O request to associate the command with.
884	* @param uLun The LUN the command is for.
885	* @param pbCdb The SCSI CDB containing the command.
886	* @param cbCdb Size of the CDB in bytes.
887	* @param enmTxDir Direction of transfer.
888	* @param pvBuf Pointer tp the transfer buffer.
889	* @param cbBuf Size of the transfer buffer.
890	* @param pbSenseKey Status of the command (when return value is VERR_DEV_IO_ERROR).
891	* @param cTimeoutMillies Command timeout in milliseconds.
892	* @thread Any thread.
893	*/
894	DECLR3CALLBACKMEMBER(int, pfnIoReqSendScsiCmd,(PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint32_t uLun,
895	const uint8_t *pbCdb, size_t cbCdb, PDMMEDIAEXIOREQSCSITXDIR enmTxDir,
896	size_t cbBuf, uint8_t *pabSense, size_t cbSense, uint32_t cTimeoutMillies));
897
898	/**
899	* Returns the number of active I/O requests.
900	*
901	* @returns Number of active I/O requests.
902	* @param pInterface Pointer to the interface structure containing the called function pointer.
903	* @thread Any thread.
904	*/
905	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetActiveCount, (PPDMIMEDIAEX pInterface));
906
907	/**
908	* Returns the number of suspended requests.
909	*
910	* @returns Number of suspended I/O requests.
911	* @param pInterface Pointer to the interface structure containing the called function pointer.
912	* @thread Any thread.
913	*/
914	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetSuspendedCount, (PPDMIMEDIAEX pInterface));
915
916	/**
917	* Gets the first suspended request handle.
918	*
919	* @returns VBox status code.
920	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
921	* @param pInterface Pointer to the interface structure containing the called function pointer.
922	* @param phIoReq Where to store the request handle on success.
923	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
924	* @thread Any thread.
925	*
926	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
927	* changes into the active state again. The only purpose for this method for now is to make saving the state
928	* possible without breaking saved state versions.
929	*/
930	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedStart, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc));
931
932	/**
933	* Gets the next suspended request handle.
934	*
935	* @returns VBox status code.
936	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
937	* @param pInterface Pointer to the interface structure containing the called function pointer.
938	* @param hIoReq The current request handle.
939	* @param phIoReqNext Where to store the request handle on success.
940	* @param ppvIoReqAllocNext Where to store the pointer to the allocator specific memory on success.
941	* @thread Any thread.
942	*
943	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
944	* changes into the active state again. The only purpose for this method for now is to make saving the state
945	* possible without breaking saved state versions.
946	*/
947	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedNext, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq,
948	PPDMMEDIAEXIOREQ phIoReqNext, void **ppvIoReqAllocNext));
949
950	/**
951	* Saves the given I/O request state in the provided saved state unit.
952	*
953	* @returns VBox status code.
954	* @param pInterface Pointer to the interface structure containing the called function pointer.
955	* @param pSSM The SSM handle.
956	* @param hIoReq The request handle to save.
957	*/
958	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedSave, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
959
960	/**
961	* Load a suspended request state from the given saved state unit and link it into the suspended list.
962	*
963	* @returns VBox status code.
964	* @param pInterface Pointer to the interface structure containing the called function pointer.
965	* @param pSSM The SSM handle to read the state from.
966	* @param hIoReq The request handle to load the state into.
967	*/
968	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedLoad, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
969
970	} PDMIMEDIAEX;
971	/** PDMIMEDIAEX interface ID. */
972	#define PDMIMEDIAEX_IID "ae47c9a9-fa43-4b07-8f9a-b45bcc3fb8e4"
973
974	/**
975	* Data direction.
976	*/
977	typedef enum PDMSCSIREQUESTTXDIR
978	{
979	PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
980	PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
981	PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
982	PDMSCSIREQUESTTXDIR_NONE = 0x03,
983	PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
984	} PDMSCSIREQUESTTXDIR;
985
986	/**
987	* SCSI request structure.
988	*/
989	typedef struct PDMSCSIREQUEST
990	{
991	/** The logical unit. */
992	uint32_t uLogicalUnit;
993	/** Direction of the data flow. */
994	PDMSCSIREQUESTTXDIR uDataDirection;
995	/** Size of the SCSI CDB. */
996	uint32_t cbCDB;
997	/** Pointer to the SCSI CDB. */
998	uint8_t *pbCDB;
999	/** Overall size of all scatter gather list elements
1000	* for data transfer if any. */
1001	uint32_t cbScatterGather;
1002	/** Number of elements in the scatter gather list. */
1003	uint32_t cScatterGatherEntries;
1004	/** Pointer to the head of the scatter gather list. */
1005	PRTSGSEG paScatterGatherHead;
1006	/** Size of the sense buffer. */
1007	uint32_t cbSenseBuffer;
1008	/** Pointer to the sense buffer. *
1009	* Current assumption that the sense buffer is not scattered. */
1010	uint8_t *pbSenseBuffer;
1011	/** Opaque user data for use by the device. Left untouched by everything else! */
1012	void *pvUser;
1013	} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
1014	/** Pointer to a const SCSI request structure. */
1015	typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
1016
1017	/** Pointer to a SCSI port interface. */
1018	typedef struct PDMISCSIPORT *PPDMISCSIPORT;
1019	/**
1020	* SCSI command execution port interface (down).
1021	* Pair with PDMISCSICONNECTOR.
1022	*/
1023	typedef struct PDMISCSIPORT
1024	{
1025
1026	/**
1027	* Notify the device on request completion.
1028	*
1029	* @returns VBox status code.
1030	* @param pInterface Pointer to this interface.
1031	* @param pSCSIRequest Pointer to the finished SCSI request.
1032	* @param rcCompletion SCSI_STATUS_* code for the completed request.
1033	* @param fRedo Flag whether the request can to be redone
1034	* when it failed.
1035	* @param rcReq The status code the request completed with (VERR_*)
1036	* Should be only used to choose the correct error message
1037	* displayed to the user if the error can be fixed by him
1038	* (fRedo is true).
1039	*/
1040	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest,
1041	int rcCompletion, bool fRedo, int rcReq));
1042
1043	/**
1044	* Returns the storage controller name, instance and LUN of the attached medium.
1045	*
1046	* @returns VBox status.
1047	* @param pInterface Pointer to this interface.
1048	* @param ppcszController Where to store the name of the storage controller.
1049	* @param piInstance Where to store the instance number of the controller.
1050	* @param piLUN Where to store the LUN of the attached device.
1051	*/
1052	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMISCSIPORT pInterface, const char **ppcszController,
1053	uint32_t piInstance, uint32_t piLUN));
1054
1055	} PDMISCSIPORT;
1056	/** PDMISCSIPORT interface ID. */
1057	#define PDMISCSIPORT_IID "05d9fc3b-e38c-4b30-8344-a323feebcfe5"
1058
1059	/**
1060	* LUN type.
1061	*/
1062	typedef enum PDMSCSILUNTYPE
1063	{
1064	PDMSCSILUNTYPE_INVALID = 0,
1065	PDMSCSILUNTYPE_SBC, /** Hard disk (SBC) */
1066	PDMSCSILUNTYPE_MMC, /** CD/DVD drive (MMC) */
1067	PDMSCSILUNTYPE_SSC, /** Tape drive (SSC) */
1068	PDMSCSILUNTYPE_32BIT_HACK = 0x7fffffff
1069	} PDMSCSILUNTYPE, *PPDMSCSILUNTYPE;
1070
1071
1072	/** Pointer to a SCSI connector interface. */
1073	typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
1074	/**
1075	* SCSI command execution connector interface (up).
1076	* Pair with PDMISCSIPORT.
1077	*/
1078	typedef struct PDMISCSICONNECTOR
1079	{
1080
1081	/**
1082	* Submits a SCSI request for execution.
1083	*
1084	* @returns VBox status code.
1085	* @param pInterface Pointer to this interface.
1086	* @param pSCSIRequest Pointer to the SCSI request to execute.
1087	*/
1088	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
1089
1090	/**
1091	* Queries the type of the attached LUN.
1092	*
1093	* @returns VBox status code.
1094	* @param pInterface Pointer to this interface.
1095	* @param iLUN The logical unit number.
1096	* @param pSCSIRequest Pointer to the LUN to be returned.
1097	*/
1098	DECLR3CALLBACKMEMBER(int, pfnQueryLUNType, (PPDMISCSICONNECTOR pInterface, uint32_t iLun, PPDMSCSILUNTYPE pLUNType));
1099
1100	} PDMISCSICONNECTOR;
1101	/** PDMISCSICONNECTOR interface ID. */
1102	#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
1103
1104	/** @} */
1105
1106	RT_C_DECLS_END
1107
1108	#endif

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

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

Download in other formats: