pdmstorageifs.h@ 64660

Last change on this file since 64660 was 64660, checked in by vboxsync, 8 years ago
pdmstorageifs.h,AHCI,NVMe,LsiLogic,BusLogic,DrvSCSI: Prepare for a new callback in PDMIMEDIAEXPORT which can reduce the overhead of copying data between buffers under certain circumstances
Property svn:eol-style set to `native` Property svn:keywords set to `Id`
File size: 46.8 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 pcbBuf Size of the transfer buffer.
294	* @param pabSense Status of the command (when return value is VERR_DEV_IO_ERROR).
295	* @param cbSense Size of the sense buffer in bytes.
296	* @param cTimeoutMillies Command timeout in milliseconds.
297	* @thread Any thread.
298	*/
299	DECLR3CALLBACKMEMBER(int, pfnSendCmd,(PPDMIMEDIA pInterface, const uint8_t *pbCmd, PDMMEDIATXDIR enmTxDir,
300	void pvBuf, uint32_t pcbBuf, uint8_t *pabSense, size_t cbSense,
301	uint32_t cTimeoutMillies));
302
303	/**
304	* Merge medium contents during a live snapshot deletion. All details
305	* must have been configured through CFGM or this will fail.
306	* This method is optional (i.e. the function pointer may be NULL).
307	*
308	* @returns VBox status code.
309	* @param pInterface Pointer to the interface structure containing the called function pointer.
310	* @param pfnProgress Function pointer for progress notification.
311	* @param pvUser Opaque user data for progress notification.
312	* @thread Any thread.
313	*/
314	DECLR3CALLBACKMEMBER(int, pfnMerge,(PPDMIMEDIA pInterface, PFNSIMPLEPROGRESS pfnProgress, void *pvUser));
315
316	/**
317	* Sets the secret key retrieval interface to use to get secret keys.
318	*
319	* @returns VBox status code.
320	* @param pInterface Pointer to the interface structure containing the called function pointer.
321	* @param pIfSecKey The secret key interface to use.
322	* Use NULL to clear the currently set interface and clear all secret
323	* keys from the user.
324	* @param pIfSecKeyHlp The secret key helper interface to use.
325	* @thread Any thread.
326	*/
327	DECLR3CALLBACKMEMBER(int, pfnSetSecKeyIf,(PPDMIMEDIA pInterface, PPDMISECKEY pIfSecKey,
328	PPDMISECKEYHLP pIfSecKeyHlp));
329
330	/**
331	* Get the media size in bytes.
332	*
333	* @returns Media size in bytes.
334	* @param pInterface Pointer to the interface structure containing the called function pointer.
335	* @thread Any thread.
336	*/
337	DECLR3CALLBACKMEMBER(uint64_t, pfnGetSize,(PPDMIMEDIA pInterface));
338
339	/**
340	* Gets the media sector size in bytes.
341	*
342	* @returns Media sector size in bytes.
343	* @param pInterface Pointer to the interface structure containing the called function pointer.
344	* @thread Any thread.
345	*/
346	DECLR3CALLBACKMEMBER(uint32_t, pfnGetSectorSize,(PPDMIMEDIA pInterface));
347
348	/**
349	* Check if the media is readonly or not.
350	*
351	* @returns true if readonly.
352	* @returns false if read/write.
353	* @param pInterface Pointer to the interface structure containing the called function pointer.
354	* @thread Any thread.
355	*/
356	DECLR3CALLBACKMEMBER(bool, pfnIsReadOnly,(PPDMIMEDIA pInterface));
357
358	/**
359	* Returns whether the medium should be marked as rotational or not.
360	*
361	* @returns true if non rotating medium.
362	* @returns false if rotating medium.
363	* @param pInterface Pointer to the interface structure containing the called function pointer.
364	* @thread Any thread.
365	*/
366	DECLR3CALLBACKMEMBER(bool, pfnIsNonRotational,(PPDMIMEDIA pInterface));
367
368	/**
369	* Get stored media geometry (physical CHS, PCHS) - BIOS property.
370	* This is an optional feature of a media.
371	*
372	* @returns VBox status code.
373	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
374	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetPCHSGeometry() yet.
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 Any thread.
379	*/
380	DECLR3CALLBACKMEMBER(int, pfnBiosGetPCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pPCHSGeometry));
381
382	/**
383	* Store the media geometry (physical CHS, PCHS) - 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	* @param pInterface Pointer to the interface structure containing the called function pointer.
389	* @param pPCHSGeometry Pointer to PCHS geometry (cylinders/heads/sectors).
390	* @remark This has no influence on the read/write operations.
391	* @thread The emulation thread.
392	*/
393	DECLR3CALLBACKMEMBER(int, pfnBiosSetPCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pPCHSGeometry));
394
395	/**
396	* Get stored media geometry (logical CHS, LCHS) - BIOS property.
397	* This is an optional feature of a media.
398	*
399	* @returns VBox status code.
400	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
401	* @returns VERR_PDM_GEOMETRY_NOT_SET if the geometry hasn't been set using pfnBiosSetLCHSGeometry() yet.
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 Any thread.
406	*/
407	DECLR3CALLBACKMEMBER(int, pfnBiosGetLCHSGeometry,(PPDMIMEDIA pInterface, PPDMMEDIAGEOMETRY pLCHSGeometry));
408
409	/**
410	* Store the media geometry (logical CHS, LCHS) - BIOS property.
411	* This is an optional feature of a media.
412	*
413	* @returns VBox status code.
414	* @returns VERR_NOT_IMPLEMENTED if the media doesn't support storing the geometry.
415	* @param pInterface Pointer to the interface structure containing the called function pointer.
416	* @param pLCHSGeometry Pointer to LCHS geometry (cylinders/heads/sectors).
417	* @remark This has no influence on the read/write operations.
418	* @thread The emulation thread.
419	*/
420	DECLR3CALLBACKMEMBER(int, pfnBiosSetLCHSGeometry,(PPDMIMEDIA pInterface, PCPDMMEDIAGEOMETRY pLCHSGeometry));
421
422	/**
423	* Checks if the device should be visible to the BIOS or not.
424	*
425	* @returns true if the device is visible to the BIOS.
426	* @returns false if the device is not visible to the BIOS.
427	* @param pInterface Pointer to the interface structure containing the called function pointer.
428	* @thread Any thread.
429	*/
430	DECLR3CALLBACKMEMBER(bool, pfnBiosIsVisible,(PPDMIMEDIA pInterface));
431
432	/**
433	* Gets the media type.
434	*
435	* @returns media type.
436	* @param pInterface Pointer to the interface structure containing the called function pointer.
437	* @thread Any thread.
438	*/
439	DECLR3CALLBACKMEMBER(PDMMEDIATYPE, pfnGetType,(PPDMIMEDIA pInterface));
440
441	/**
442	* Gets the UUID of the media drive.
443	*
444	* @returns VBox status code.
445	* @param pInterface Pointer to the interface structure containing the called function pointer.
446	* @param pUuid Where to store the UUID on success.
447	* @thread Any thread.
448	*/
449	DECLR3CALLBACKMEMBER(int, pfnGetUuid,(PPDMIMEDIA pInterface, PRTUUID pUuid));
450
451	/**
452	* Discards the given range.
453	*
454	* @returns VBox status code.
455	* @param pInterface Pointer to the interface structure containing the called function pointer.
456	* @param paRanges Array of ranges to discard.
457	* @param cRanges Number of entries in the array.
458	* @thread Any thread.
459	*/
460	DECLR3CALLBACKMEMBER(int, pfnDiscard,(PPDMIMEDIA pInterface, PCRTRANGE paRanges, unsigned cRanges));
461
462	} PDMIMEDIA;
463	/** PDMIMEDIA interface ID. */
464	#define PDMIMEDIA_IID "d344aeaa-3ad0-4563-bb03-2733383e9230"
465
466
467	/**
468	* Opaque I/O request handle.
469	*
470	* The specific content depends on the driver implementing this interface.
471	*/
472	typedef struct PDMMEDIAEXIOREQINT *PDMMEDIAEXIOREQ;
473	/** Pointer to an I/O request handle. */
474	typedef PDMMEDIAEXIOREQ *PPDMMEDIAEXIOREQ;
475
476	/** A I/O request ID. */
477	typedef uint64_t PDMMEDIAEXIOREQID;
478
479	/**
480	* I/O Request Type.
481	*/
482	typedef enum PDMMEDIAEXIOREQTYPE
483	{
484	/** Invalid tpe. */
485	PDMMEDIAEXIOREQTYPE_INVALID = 0,
486	/** Flush request. */
487	PDMMEDIAEXIOREQTYPE_FLUSH,
488	/** Write request. */
489	PDMMEDIAEXIOREQTYPE_WRITE,
490	/** Read request. */
491	PDMMEDIAEXIOREQTYPE_READ,
492	/** Discard request. */
493	PDMMEDIAEXIOREQTYPE_DISCARD,
494	/** SCSI command. */
495	PDMMEDIAEXIOREQTYPE_SCSI
496	} PDMMEDIAEXIOREQTYPE;
497	/** Pointer to a I/O request type. */
498	typedef PDMMEDIAEXIOREQTYPE *PPDMMEDIAEXIOREQTYPE;
499
500	/**
501	* Data direction for raw SCSI commands.
502	*/
503	typedef enum PDMMEDIAEXIOREQSCSITXDIR
504	{
505	/** Invalid data direction. */
506	PDMMEDIAEXIOREQSCSITXDIR_INVALID = 0,
507	/** Direction is unknown. */
508	PDMMEDIAEXIOREQSCSITXDIR_UNKNOWN,
509	/** Direction is from device to host. */
510	PDMMEDIAEXIOREQSCSITXDIR_FROM_DEVICE,
511	/** Direction is from host to device. */
512	PDMMEDIAEXIOREQSCSITXDIR_TO_DEVICE,
513	/** No data transfer associated with this request. */
514	PDMMEDIAEXIOREQSCSITXDIR_NONE,
515	/** 32bit hack. */
516	PDMMEDIAEXIOREQSCSITXDIR_32BIT_HACK = 0x7fffffff
517	} PDMMEDIAEXIOREQSCSITXDIR;
518
519	/**
520	* I/O request state.
521	*/
522	typedef enum PDMMEDIAEXIOREQSTATE
523	{
524	/** Invalid state. */
525	PDMMEDIAEXIOREQSTATE_INVALID = 0,
526	/** The request is active and being processed. */
527	PDMMEDIAEXIOREQSTATE_ACTIVE,
528	/** The request is suspended due to an error and no processing will take place. */
529	PDMMEDIAEXIOREQSTATE_SUSPENDED,
530	/** 32bit hack. */
531	PDMMEDIAEXIOREQSTATE_32BIT_HACK = 0x7fffffff
532	} PDMMEDIAEXIOREQSTATE;
533	/** Pointer to a I/O request state. */
534	typedef PDMMEDIAEXIOREQSTATE *PPDMMEDIAEXIOREQSTATE;
535
536	/** @name Supported feature flags
537	* @{ */
538	/** I/O requests will execute asynchronously by default. */
539	#define PDMIMEDIAEX_FEATURE_F_ASYNC RT_BIT_32(0)
540	/** The discard request is supported. */
541	#define PDMIMEDIAEX_FEATURE_F_DISCARD RT_BIT_32(1)
542	/** The send raw SCSI command request is supported. */
543	#define PDMIMEDIAEX_FEATURE_F_RAWSCSICMD RT_BIT_32(2)
544	/** Mask of valid flags. */
545	#define PDMIMEDIAEX_FEATURE_F_VALID (PDMIMEDIAEX_FEATURE_F_ASYNC \| PDMIMEDIAEX_FEATURE_F_DISCARD \| PDMIMEDIAEX_FEATURE_F_RAWSCSICMD)
546	/** @} */
547
548	/** @name I/O request specific flags
549	* @{ */
550	/** Default behavior (async I/O).*/
551	#define PDMIMEDIAEX_F_DEFAULT (0)
552	/** The I/O request will be executed synchronously. */
553	#define PDMIMEDIAEX_F_SYNC RT_BIT_32(0)
554	/** Whether to suspend the VM on a recoverable error with
555	* an appropriate error message (disk full, etc.).
556	* The request will be retried by the driver implementing the interface
557	* when the VM resumes the next time. However before suspending the request
558	* the owner of the request will be notified using the PDMMEDIAEXPORT::pfnIoReqStateChanged.
559	* The same goes for resuming the request after the VM was resumed.
560	*/
561	#define PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR RT_BIT_32(1)
562	/** Mask of valid flags. */
563	#define PDMIMEDIAEX_F_VALID (PDMIMEDIAEX_F_SYNC \| PDMIMEDIAEX_F_SUSPEND_ON_RECOVERABLE_ERR)
564	/** @} */
565
566	/** Pointer to an extended media notification interface. */
567	typedef struct PDMIMEDIAEXPORT *PPDMIMEDIAEXPORT;
568
569	/**
570	* Asynchronous version of the media interface (up).
571	* Pair with PDMIMEDIAEXPORT.
572	*/
573	typedef struct PDMIMEDIAEXPORT
574	{
575	/**
576	* Notify completion of a I/O request.
577	*
578	* @returns VBox status code.
579	* @param pInterface Pointer to the interface structure containing the called function pointer.
580	* @param hIoReq The I/O request handle.
581	* @param pvIoReqAlloc The allocator specific memory for this request.
582	* @param rcReq IPRT Status code of the completed request.
583	* VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
584	* PDMIMEDIAEX::pfnIoReqCancel.
585	* @thread Any thread.
586	*/
587	DECLR3CALLBACKMEMBER(int, pfnIoReqCompleteNotify, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
588	void *pvIoReqAlloc, int rcReq));
589
590	/**
591	* Copy data from the memory buffer of the caller to the callees memory buffer for the given request.
592	*
593	* @returns VBox status code.
594	* @retval VERR_PDM_MEDIAEX_IOBUF_OVERFLOW if there is not enough room to store the data.
595	* @param pInterface Pointer to the interface structure containing the called function pointer.
596	* @param hIoReq The I/O request handle.
597	* @param pvIoReqAlloc The allocator specific memory for this request.
598	* @param offDst The destination offset from the start to write the data to.
599	* @param pSgBuf The S/G buffer to read the data from.
600	* @param cbCopy How many bytes to copy.
601	*/
602	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyFromBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
603	void *pvIoReqAlloc, uint32_t offDst, PRTSGBUF pSgBuf,
604	size_t cbCopy));
605
606	/**
607	* Copy data to the memory buffer of the caller from the callees memory buffer for the given request.
608	*
609	* @returns VBox status code.
610	* @retval VERR_PDM_MEDIAEX_IOBUF_UNDERRUN if there is not enough data to copy from the buffer.
611	* @param pInterface Pointer to the interface structure containing the called function pointer.
612	* @param hIoReq The I/O request handle.
613	* @param pvIoReqAlloc The allocator specific memory for this request.
614	* @param offSrc The offset from the start of the buffer to read the data from.
615	* @param pSgBuf The S/G buffer to write the data to.
616	* @param cbCopy How many bytes to copy.
617	*/
618	DECLR3CALLBACKMEMBER(int, pfnIoReqCopyToBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
619	void *pvIoReqAlloc, uint32_t offSrc, PRTSGBUF pSgBuf,
620	size_t cbCopy));
621
622	/**
623	* Queries a pointer to the memory buffer for the request from the drive/device above.
624	*
625	* @returns VBox status code.
626	* @retval VERR_NOT_SUPPORTED if this is not supported for this request.
627	* @param pInterface Pointer to the interface structure containing the called function pointer.
628	* @param hIoReq The I/O request handle.
629	* @param pvIoReqAlloc The allocator specific memory for this request.
630	* @param ppvBuf Where to store the pointer to the guest buffer on success.
631	* @param pcbBuf Where to store the size of the buffer on success.
632	*
633	* @note This is an optional feature of the entity implementing this interface to avoid overhead
634	* by copying the data between buffers. If NULL it is not supported at all and the caller
635	* has to resort to PDMIMEDIAEXPORT::pfnIoReqCopyToBuf and PDMIMEDIAEXPORT::pfnIoReqCopyFromBuf.
636	* The same holds when VERR_NOT_SUPPORTED is returned.
637	*
638	* On the upside the caller of this interface might not call this method at all and just
639	* use the before mentioned methods to copy the data between the buffers.
640	*/
641	DECLR3CALLBACKMEMBER(int, pfnIoReqQueryBuf, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
642	void pvIoReqAlloc, void ppvBuf, size_t pcbBuf));
643
644	/**
645	* Queries the specified amount of ranges to discard from the callee for the given I/O request.
646	*
647	* @returns VBox status code.
648	* @param pInterface Pointer to the interface structure containing the called function pointer.
649	* @param hIoReq The I/O request handle.
650	* @param pvIoReqAlloc The allocator specific memory for this request.
651	* @param idxRangeStart The range index to start with.
652	* @param cRanges How man ranges can be stored in the provided array.
653	* @param paRanges Where to store the ranges on success.
654	* @param *pcRanges Where to store the number of ranges copied over on success.
655	*/
656	DECLR3CALLBACKMEMBER(int, pfnIoReqQueryDiscardRanges, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
657	void *pvIoReqAlloc, uint32_t idxRangeStart,
658	uint32_t cRanges, PRTRANGE paRanges,
659	uint32_t *pcRanges));
660
661	/**
662	* Notify the request owner about a state change for the request.
663	*
664	* @returns nothing.
665	* @param pInterface Pointer to the interface structure containing the called function pointer.
666	* @param hIoReq The I/O request handle.
667	* @param pvIoReqAlloc The allocator specific memory for this request.
668	* @param enmState The new state of the request.
669	*/
670	DECLR3CALLBACKMEMBER(void, pfnIoReqStateChanged, (PPDMIMEDIAEXPORT pInterface, PDMMEDIAEXIOREQ hIoReq,
671	void *pvIoReqAlloc, PDMMEDIAEXIOREQSTATE enmState));
672
673	/**
674	* Informs the device that the underlying medium was ejected.
675	*
676	* @returns nothing.
677	* @param pInterface Pointer to the interface structure containing the called function pointer.
678	*/
679	DECLR3CALLBACKMEMBER(void, pfnMediumEjected, (PPDMIMEDIAEXPORT pInterface));
680
681	} PDMIMEDIAEXPORT;
682
683	/** PDMIMEDIAAEXPORT interface ID. */
684	#define PDMIMEDIAEXPORT_IID "0ae2e534-6c28-41d6-9a88-7f88f2cb2ff8"
685
686
687	/** Pointer to an extended media interface. */
688	typedef struct PDMIMEDIAEX *PPDMIMEDIAEX;
689
690	/**
691	* Extended version of PDMIMEDIA (down).
692	* Pair with PDMIMEDIAEXPORT.
693	*/
694	typedef struct PDMIMEDIAEX
695	{
696	/**
697	* Queries the features supported by the entity implementing this interface.
698	*
699	* @returns VBox status code.
700	* @param pInterface Pointer to the interface structure containing the called function pointer.
701	* @param pfFeatures Where to store the supported feature flags on success.
702	*/
703	DECLR3CALLBACKMEMBER(int, pfnQueryFeatures, (PPDMIMEDIAEX pInterface, uint32_t *pfFeatures));
704
705	/**
706	* Sets the size of the allocator specific memory for a I/O request.
707	*
708	* @returns VBox status code.
709	* @param pInterface Pointer to the interface structure containing the called function pointer.
710	* @param cbIoReqAlloc The size of the allocator specific memory in bytes.
711	* @thread EMT.
712	*/
713	DECLR3CALLBACKMEMBER(int, pfnIoReqAllocSizeSet, (PPDMIMEDIAEX pInterface, size_t cbIoReqAlloc));
714
715	/**
716	* Allocates a new I/O request.
717	*
718	* @returns VBox status code.
719	* @retval VERR_PDM_MEDIAEX_IOREQID_CONFLICT if the ID belongs to a still active request.
720	* @param pInterface Pointer to the interface structure containing the called function pointer.
721	* @param phIoReq Where to store the handle to the new I/O request on success.
722	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
723	* NULL if the memory size was not set or set to 0.
724	* @param uIoReqId A custom request ID which can be used to cancel the request.
725	* @param fFlags A combination of PDMIMEDIAEX_F_* flags.
726	* @thread Any thread.
727	*/
728	DECLR3CALLBACKMEMBER(int, pfnIoReqAlloc, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc,
729	PDMMEDIAEXIOREQID uIoReqId, uint32_t fFlags));
730
731	/**
732	* Frees a given I/O request.
733	*
734	* @returns VBox status code.
735	* @retval VERR_PDM_MEDIAEX_IOREQ_INVALID_STATE if the given request is still active.
736	* @param pInterface Pointer to the interface structure containing the called function pointer.
737	* @param hIoReq The I/O request to free.
738	* @thread Any thread.
739	*/
740	DECLR3CALLBACKMEMBER(int, pfnIoReqFree, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
741
742	/**
743	* Queries the residual amount of data not transfered when the request completed.
744	*
745	* @returns VBox status code.
746	* @retval VERR_PDM_MEDIAEX_IOREQ_INVALID_STATE has not completed yet.
747	* @param pInterface Pointer to the interface structure containing the called function pointer.
748	* @param hIoReq The I/O request.
749	* @param pcbResidual Where to store the amount of resdiual data in bytes.
750	* @thread Any thread.
751	*/
752	DECLR3CALLBACKMEMBER(int, pfnIoReqQueryResidual, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, size_t *pcbResidual));
753
754	/**
755	* Queries the residual amount of data not transfered when the request completed.
756	*
757	* @returns VBox status code.
758	* @retval VERR_PDM_MEDIAEX_IOREQ_INVALID_STATE has not completed yet.
759	* @param pInterface Pointer to the interface structure containing the called function pointer.
760	* @param hIoReq The I/O request.
761	* @param pcbXfer Where to store the amount of resdiual data in bytes.
762	* @thread Any thread.
763	*
764	* @note For simple read/write requests this returns the amount to read/write as given to the
765	* PDMIMEDIAEX::pfnIoReqRead or PDMIMEDIAEX::pfnIoReqWrite call.
766	* For SCSI commands this returns the transfer size as given in the provided CDB.
767	*/
768	DECLR3CALLBACKMEMBER(int, pfnIoReqQueryXferSize, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, size_t *pcbXfer));
769
770	/**
771	* Cancels all I/O active requests.
772	*
773	* @returns VBox status code.
774	* @param pInterface Pointer to the interface structure containing the called function pointer.
775	* @thread Any thread.
776	*/
777	DECLR3CALLBACKMEMBER(int, pfnIoReqCancelAll, (PPDMIMEDIAEX pInterface));
778
779	/**
780	* Cancels a I/O request identified by the ID.
781	*
782	* @returns VBox status code.
783	* @retval VERR_PDM_MEDIAEX_IOREQID_NOT_FOUND if the given ID could not be found in the active request list.
784	* (The request has either completed already or an invalid ID was given).
785	* @param pInterface Pointer to the interface structure containing the called function pointer.
786	* @param uIoReqId The I/O request ID
787	* @thread Any thread.
788	*/
789	DECLR3CALLBACKMEMBER(int, pfnIoReqCancel, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQID uIoReqId));
790
791	/**
792	* Start a reading request.
793	*
794	* @returns VBox status code.
795	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
796	* PDMIMEDIAEX::pfnIoReqCancel.
797	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
798	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
799	* @retval VINF_SUCCESS if the request completed successfully.
800	* @param pInterface Pointer to the interface structure containing the called function pointer.
801	* @param hIoReq The I/O request to associate the read with.
802	* @param off Offset to start reading from. Must be aligned to a sector boundary.
803	* @param cbRead Number of bytes to read. Must be aligned to a sector boundary.
804	* @thread Any thread.
805	*/
806	DECLR3CALLBACKMEMBER(int, pfnIoReqRead, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbRead));
807
808	/**
809	* Start a writing 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 write with.
819	* @param off Offset to start reading from. Must be aligned to a sector boundary.
820	* @param cbWrite Number of bytes to write. Must be aligned to a sector boundary.
821	* @thread Any thread.
822	*/
823	DECLR3CALLBACKMEMBER(int, pfnIoReqWrite, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint64_t off, size_t cbWrite));
824
825	/**
826	* Flush everything to disk.
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 flush with.
836	* @thread Any thread.
837	*/
838	DECLR3CALLBACKMEMBER(int, pfnIoReqFlush, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq));
839
840	/**
841	* Discards the given range.
842	*
843	* @returns VBox status code.
844	* @retval VERR_PDM_MEDIAEX_IOREQ_CANCELED if the request was canceled by a call to
845	* PDMIMEDIAEX::pfnIoReqCancel.
846	* @retval VINF_PDM_MEDIAEX_IOREQ_IN_PROGRESS if the request was successfully submitted but is still in progress.
847	* Completion will be notified through PDMIMEDIAEXPORT::pfnIoReqCompleteNotify with the appropriate status code.
848	* @retval VINF_SUCCESS if the request completed successfully.
849	* @param pInterface Pointer to the interface structure containing the called function pointer.
850	* @param hIoReq The I/O request to associate the discard with.
851	* @param cRangesMax The maximum number of ranges this request has associated, this must not be accurate
852	* but can actually be bigger than the amount of ranges actually available.
853	* @thread Any thread.
854	*/
855	DECLR3CALLBACKMEMBER(int, pfnIoReqDiscard, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, unsigned cRangesMax));
856
857	/**
858	* Send a raw command to the underlying device (CDROM).
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	* @param pInterface Pointer to the interface structure containing the called function pointer.
866	* @param hIoReq The I/O request to associate the command with.
867	* @param uLun The LUN the command is for.
868	* @param pbCdb The SCSI CDB containing the command.
869	* @param cbCdb Size of the CDB in bytes.
870	* @param enmTxDir Direction of transfer.
871	* @param cbBuf Size of the transfer buffer.
872	* @param pabSense Where to store the optional sense key.
873	* @param cbSense Size of the sense key buffer.
874	* @param pu8ScsiSts Where to store the SCSI status on success.
875	* @param cTimeoutMillies Command timeout in milliseconds.
876	* @thread Any thread.
877	*/
878	DECLR3CALLBACKMEMBER(int, pfnIoReqSendScsiCmd,(PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq, uint32_t uLun,
879	const uint8_t *pbCdb, size_t cbCdb, PDMMEDIAEXIOREQSCSITXDIR enmTxDir,
880	size_t cbBuf, uint8_t pabSense, size_t cbSense, uint8_t pu8ScsiSts,
881	uint32_t cTimeoutMillies));
882
883	/**
884	* Returns the number of active I/O requests.
885	*
886	* @returns Number of active I/O requests.
887	* @param pInterface Pointer to the interface structure containing the called function pointer.
888	* @thread Any thread.
889	*/
890	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetActiveCount, (PPDMIMEDIAEX pInterface));
891
892	/**
893	* Returns the number of suspended requests.
894	*
895	* @returns Number of suspended I/O requests.
896	* @param pInterface Pointer to the interface structure containing the called function pointer.
897	* @thread Any thread.
898	*/
899	DECLR3CALLBACKMEMBER(uint32_t, pfnIoReqGetSuspendedCount, (PPDMIMEDIAEX pInterface));
900
901	/**
902	* Gets the first suspended request handle.
903	*
904	* @returns VBox status code.
905	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
906	* @param pInterface Pointer to the interface structure containing the called function pointer.
907	* @param phIoReq Where to store the request handle on success.
908	* @param ppvIoReqAlloc Where to store the pointer to the allocator specific memory on success.
909	* @thread Any thread.
910	*
911	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
912	* changes into the active state again. The only purpose for this method for now is to make saving the state
913	* possible without breaking saved state versions.
914	*/
915	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedStart, (PPDMIMEDIAEX pInterface, PPDMMEDIAEXIOREQ phIoReq, void **ppvIoReqAlloc));
916
917	/**
918	* Gets the next suspended request handle.
919	*
920	* @returns VBox status code.
921	* @retval VERR_NOT_FOUND if there is no suspended request waiting.
922	* @param pInterface Pointer to the interface structure containing the called function pointer.
923	* @param hIoReq The current request handle.
924	* @param phIoReqNext Where to store the request handle on success.
925	* @param ppvIoReqAllocNext Where to store the pointer to the allocator specific memory on success.
926	* @thread Any thread.
927	*
928	* @note This should only be called when the VM is suspended to make sure the request doesn't suddenly
929	* changes into the active state again. The only purpose for this method for now is to make saving the state
930	* possible without breaking saved state versions.
931	*/
932	DECLR3CALLBACKMEMBER(int, pfnIoReqQuerySuspendedNext, (PPDMIMEDIAEX pInterface, PDMMEDIAEXIOREQ hIoReq,
933	PPDMMEDIAEXIOREQ phIoReqNext, void **ppvIoReqAllocNext));
934
935	/**
936	* Saves the given I/O request state in the provided saved state unit.
937	*
938	* @returns VBox status code.
939	* @param pInterface Pointer to the interface structure containing the called function pointer.
940	* @param pSSM The SSM handle.
941	* @param hIoReq The request handle to save.
942	*/
943	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedSave, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
944
945	/**
946	* Load a suspended request state from the given saved state unit and link it into the suspended list.
947	*
948	* @returns VBox status code.
949	* @param pInterface Pointer to the interface structure containing the called function pointer.
950	* @param pSSM The SSM handle to read the state from.
951	* @param hIoReq The request handle to load the state into.
952	*/
953	DECLR3CALLBACKMEMBER(int, pfnIoReqSuspendedLoad, (PPDMIMEDIAEX pInterface, PSSMHANDLE pSSM, PDMMEDIAEXIOREQ hIoReq));
954
955	} PDMIMEDIAEX;
956	/** PDMIMEDIAEX interface ID. */
957	#define PDMIMEDIAEX_IID "1f82b709-a9f7-4928-ad50-e879c9bbeba1"
958
959	/**
960	* Data direction.
961	*/
962	typedef enum PDMSCSIREQUESTTXDIR
963	{
964	PDMSCSIREQUESTTXDIR_UNKNOWN = 0x00,
965	PDMSCSIREQUESTTXDIR_FROM_DEVICE = 0x01,
966	PDMSCSIREQUESTTXDIR_TO_DEVICE = 0x02,
967	PDMSCSIREQUESTTXDIR_NONE = 0x03,
968	PDMSCSIREQUESTTXDIR_32BIT_HACK = 0x7fffffff
969	} PDMSCSIREQUESTTXDIR;
970
971	/**
972	* SCSI request structure.
973	*/
974	typedef struct PDMSCSIREQUEST
975	{
976	/** The logical unit. */
977	uint32_t uLogicalUnit;
978	/** Direction of the data flow. */
979	PDMSCSIREQUESTTXDIR uDataDirection;
980	/** Size of the SCSI CDB. */
981	uint32_t cbCDB;
982	/** Pointer to the SCSI CDB. */
983	uint8_t *pbCDB;
984	/** Overall size of all scatter gather list elements
985	* for data transfer if any. */
986	uint32_t cbScatterGather;
987	/** Number of elements in the scatter gather list. */
988	uint32_t cScatterGatherEntries;
989	/** Pointer to the head of the scatter gather list. */
990	PRTSGSEG paScatterGatherHead;
991	/** Size of the sense buffer. */
992	uint32_t cbSenseBuffer;
993	/** Pointer to the sense buffer. *
994	* Current assumption that the sense buffer is not scattered. */
995	uint8_t *pbSenseBuffer;
996	/** Opaque user data for use by the device. Left untouched by everything else! */
997	void *pvUser;
998	} PDMSCSIREQUEST, *PPDMSCSIREQUEST;
999	/** Pointer to a const SCSI request structure. */
1000	typedef const PDMSCSIREQUEST *PCSCSIREQUEST;
1001
1002	/** Pointer to a SCSI port interface. */
1003	typedef struct PDMISCSIPORT *PPDMISCSIPORT;
1004	/**
1005	* SCSI command execution port interface (down).
1006	* Pair with PDMISCSICONNECTOR.
1007	*/
1008	typedef struct PDMISCSIPORT
1009	{
1010
1011	/**
1012	* Notify the device on request completion.
1013	*
1014	* @returns VBox status code.
1015	* @param pInterface Pointer to this interface.
1016	* @param pSCSIRequest Pointer to the finished SCSI request.
1017	* @param rcCompletion SCSI_STATUS_* code for the completed request.
1018	* @param fRedo Flag whether the request can to be redone
1019	* when it failed.
1020	* @param rcReq The status code the request completed with (VERR_*)
1021	* Should be only used to choose the correct error message
1022	* displayed to the user if the error can be fixed by him
1023	* (fRedo is true).
1024	*/
1025	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestCompleted, (PPDMISCSIPORT pInterface, PPDMSCSIREQUEST pSCSIRequest,
1026	int rcCompletion, bool fRedo, int rcReq));
1027
1028	/**
1029	* Returns the storage controller name, instance and LUN of the attached medium.
1030	*
1031	* @returns VBox status.
1032	* @param pInterface Pointer to this interface.
1033	* @param ppcszController Where to store the name of the storage controller.
1034	* @param piInstance Where to store the instance number of the controller.
1035	* @param piLUN Where to store the LUN of the attached device.
1036	*/
1037	DECLR3CALLBACKMEMBER(int, pfnQueryDeviceLocation, (PPDMISCSIPORT pInterface, const char **ppcszController,
1038	uint32_t piInstance, uint32_t piLUN));
1039
1040	} PDMISCSIPORT;
1041	/** PDMISCSIPORT interface ID. */
1042	#define PDMISCSIPORT_IID "05d9fc3b-e38c-4b30-8344-a323feebcfe5"
1043
1044	/**
1045	* LUN type.
1046	*/
1047	typedef enum PDMSCSILUNTYPE
1048	{
1049	PDMSCSILUNTYPE_INVALID = 0,
1050	PDMSCSILUNTYPE_SBC, /** Hard disk (SBC) */
1051	PDMSCSILUNTYPE_MMC, /** CD/DVD drive (MMC) */
1052	PDMSCSILUNTYPE_SSC, /** Tape drive (SSC) */
1053	PDMSCSILUNTYPE_32BIT_HACK = 0x7fffffff
1054	} PDMSCSILUNTYPE, *PPDMSCSILUNTYPE;
1055
1056
1057	/** Pointer to a SCSI connector interface. */
1058	typedef struct PDMISCSICONNECTOR *PPDMISCSICONNECTOR;
1059	/**
1060	* SCSI command execution connector interface (up).
1061	* Pair with PDMISCSIPORT.
1062	*/
1063	typedef struct PDMISCSICONNECTOR
1064	{
1065
1066	/**
1067	* Submits a SCSI request for execution.
1068	*
1069	* @returns VBox status code.
1070	* @param pInterface Pointer to this interface.
1071	* @param pSCSIRequest Pointer to the SCSI request to execute.
1072	*/
1073	DECLR3CALLBACKMEMBER(int, pfnSCSIRequestSend, (PPDMISCSICONNECTOR pInterface, PPDMSCSIREQUEST pSCSIRequest));
1074
1075	/**
1076	* Queries the type of the attached LUN.
1077	*
1078	* @returns VBox status code.
1079	* @param pInterface Pointer to this interface.
1080	* @param iLUN The logical unit number.
1081	* @param pSCSIRequest Pointer to the LUN to be returned.
1082	*/
1083	DECLR3CALLBACKMEMBER(int, pfnQueryLUNType, (PPDMISCSICONNECTOR pInterface, uint32_t iLun, PPDMSCSILUNTYPE pLUNType));
1084
1085	} PDMISCSICONNECTOR;
1086	/** PDMISCSICONNECTOR interface ID. */
1087	#define PDMISCSICONNECTOR_IID "94465fbd-a2f2-447e-88c9-7366421bfbfe"
1088
1089	/** @} */
1090
1091	RT_C_DECLS_END
1092
1093	#endif

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

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

Download in other formats: