vscsi.h@ 89363

Last change on this file since 89363 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 `Author Date Id Revision`
File size: 19.0 KB

Line
1	/* $Id: vscsi.h 85121 2020-07-08 19:33:26Z vboxsync $ */
2	/** @file
3	* VBox storage drivers - Virtual SCSI driver
4	*/
5
6	/*
7	* Copyright (C) 2006-2020 Oracle Corporation
8	*
9	* This file is part of VirtualBox Open Source Edition (OSE), as
10	* available from http://www.virtualbox.org. This file is free software;
11	* you can redistribute it and/or modify it under the terms of the GNU
12	* General Public License (GPL) as published by the Free Software
13	* Foundation, in version 2 as it comes in the "COPYING" file of the
14	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
15	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
16	*
17	* The contents of this file may alternatively be used under the terms
18	* of the Common Development and Distribution License Version 1.0
19	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
20	* VirtualBox OSE distribution, in which case the provisions of the
21	* CDDL are applicable instead of those of the GPL.
22	*
23	* You may elect to license modified versions of this file under the
24	* terms and conditions of either the GPL or the CDDL or both.
25	*/
26
27	#ifndef VBOX_INCLUDED_vscsi_h
28	#define VBOX_INCLUDED_vscsi_h
29	#ifndef RT_WITHOUT_PRAGMA_ONCE
30	# pragma once
31	#endif
32
33	#include <VBox/cdefs.h>
34	#include <VBox/types.h>
35	#include <VBox/vdmedia.h>
36	#include <iprt/sg.h>
37
38	RT_C_DECLS_BEGIN
39
40	#ifdef IN_RING0
41	# error "There are no VBox VSCSI APIs available in Ring-0 Host Context!"
42	#endif
43
44	/** @defgroup grp_drv_vscsi Virtual VSCSI Driver
45	* @ingroup grp_devdrv
46	* @{
47	*/
48	/** @todo figure better grouping. */
49
50	/** A virtual SCSI device handle */
51	typedef struct VSCSIDEVICEINT *VSCSIDEVICE;
52	/** A pointer to a virtual SCSI device handle. */
53	typedef VSCSIDEVICE *PVSCSIDEVICE;
54	/** A virtual SCSI LUN handle. */
55	typedef struct VSCSILUNINT *VSCSILUN;
56	/** A pointer to a virtual SCSI LUN handle. */
57	typedef VSCSILUN *PVSCSILUN;
58	/** A virtual SCSI request handle. */
59	typedef struct VSCSIREQINT *VSCSIREQ;
60	/** A pointer to a virtual SCSI request handle. */
61	typedef VSCSIREQ *PVSCSIREQ;
62	/** A SCSI I/O request handle. */
63	typedef struct VSCSIIOREQINT *VSCSIIOREQ;
64	/** A pointer to a SCSI I/O request handle. */
65	typedef VSCSIIOREQ *PVSCSIIOREQ;
66
67	/**
68	* Virtual SCSI I/O request transfer direction.
69	*/
70	typedef enum VSCSIIOREQTXDIR
71	{
72	/** Invalid direction */
73	VSCSIIOREQTXDIR_INVALID = 0,
74	/** Read */
75	VSCSIIOREQTXDIR_READ,
76	/** Write */
77	VSCSIIOREQTXDIR_WRITE,
78	/** Flush */
79	VSCSIIOREQTXDIR_FLUSH,
80	/** Unmap */
81	VSCSIIOREQTXDIR_UNMAP,
82	/** 32bit hack */
83	VSCSIIOREQTXDIR_32BIT_HACK = 0x7fffffff
84	} VSCSIIOREQTXDIR;
85	/** Pointer to a SCSI LUN type */
86	typedef VSCSIIOREQTXDIR *PVSCSIIOREQTXDIR;
87
88	/**
89	* Virtual SCSI transfer direction as seen from the initiator.
90	*/
91	typedef enum VSCSIXFERDIR
92	{
93	/** Invalid data direction. */
94	PVSCSIXFERDIR_INVALID = 0,
95	/** Direction is unknown. */
96	VSCSIXFERDIR_UNKNOWN,
97	/** Direction is from target to initiator (aka a read). */
98	VSCSIXFERDIR_T2I,
99	/** Direction is from initiator to device (aka a write). */
100	VSCSIXFERDIR_I2T,
101	/** No data transfer associated with this request. */
102	VSCSIXFERDIR_NONE,
103	/** 32bit hack. */
104	VSCSIXFERDIR_32BIT_HACK = 0x7fffffff
105	} VSCSIXFERDIR;
106
107	/**
108	* LUN types we support
109	*/
110	typedef enum VSCSILUNTYPE
111	{
112	/** Invalid type */
113	VSCSILUNTYPE_INVALID = 0,
114	/** Hard disk (SBC) */
115	VSCSILUNTYPE_SBC,
116	/** CD/DVD drive (MMC) */
117	VSCSILUNTYPE_MMC,
118	/** Tape drive (SSC) */
119	VSCSILUNTYPE_SSC,
120	/** Last value to indicate an invalid device */
121	VSCSILUNTYPE_LAST,
122	/** 32bit hack */
123	VSCSILUNTYPE_32BIT_HACK = 0x7fffffff
124	} VSCSILUNTYPE;
125	/** Pointer to a SCSI LUN type */
126	typedef VSCSILUNTYPE *PVSCSILUNTYPE;
127
128	/** The LUN can handle the UNMAP command. */
129	#define VSCSI_LUN_FEATURE_UNMAP RT_BIT(0)
130	/** The LUN has a non rotational medium. */
131	#define VSCSI_LUN_FEATURE_NON_ROTATIONAL RT_BIT(1)
132	/** The medium of the LUN is readonly. */
133	#define VSCSI_LUN_FEATURE_READONLY RT_BIT(2)
134
135	/**
136	* Virtual SCSI LUN I/O Callback table.
137	*/
138	typedef struct VSCSILUNIOCALLBACKS
139	{
140	/**
141	* Sets the size of the allocator specific memory for a I/O request.
142	*
143	* @returns VBox status code.
144	* @param hVScsiLun Virtual SCSI LUN handle.
145	* @param pvScsiLunUser Opaque user data which may be used to identify the
146	* medium.
147	* @param cbVScsiIoReqAlloc The size of the allocator specific memory in bytes.
148	* @thread EMT.
149	*/
150	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqAllocSizeSet, (VSCSILUN hVScsiLun, void *pvScsiLunUser,
151	size_t cbVScsiIoReqAlloc));
152
153	/**
154	* Allocates a new I/O request.
155	*
156	* @returns VBox status code.
157	* @param hVScsiLun Virtual SCSI LUN handle.
158	* @param pvScsiLunUser Opaque user data which may be used to identify the
159	* medium.
160	* @param u64Tag A tag to assign to the request handle for identification later on.
161	* @param phVScsiIoReq Where to store the handle to the allocated I/O request on success.
162	* @thread Any thread.
163	*/
164	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqAlloc, (VSCSILUN hVScsiLun, void *pvScsiLunUser,
165	uint64_t u64Tag, PVSCSIIOREQ phVScsiIoReq));
166
167	/**
168	* Frees a given I/O request.
169	*
170	* @returns VBox status code.
171	* @param hVScsiLun Virtual SCSI LUN handle.
172	* @param pvScsiLunUser Opaque user data which may be used to identify the
173	* medium.
174	* @param hVScsiIoReq The VSCSI I/O request to free.
175	* @thread Any thread.
176	*/
177	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqFree, (VSCSILUN hVScsiLun, void *pvScsiLunUser, VSCSIIOREQ hVScsiIoReq));
178
179	/**
180	* Returns the number of regions for the medium.
181	*
182	* @returns Number of regions.
183	* @param hVScsiLun Virtual SCSI LUN handle.
184	* @param pvScsiLunUser Opaque user data which may be used to identify the
185	* medium.
186	*/
187	DECLR3CALLBACKMEMBER(uint32_t, pfnVScsiLunMediumGetRegionCount,(VSCSILUN hVScsiLun, void *pvScsiLunUser));
188
189	/**
190	* Queries the properties for the given region.
191	*
192	* @returns VBox status code.
193	* @retval VERR_NOT_FOUND if the region index is not known.
194	* @param hVScsiLun Virtual SCSI LUN handle.
195	* @param pvScsiLunUser Opaque user data which may be used to identify the
196	* medium.
197	* @param uRegion The region index to query the properties of.
198	* @param pu64LbaStart Where to store the starting LBA for the region on success.
199	* @param pcBlocks Where to store the number of blocks for the region on success.
200	* @param pcbBlock Where to store the size of one block in bytes on success.
201	* @param penmDataForm WHere to store the data form for the region on success.
202	*/
203	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumQueryRegionProperties,(VSCSILUN hVScsiLun, void *pvScsiLunUser,
204	uint32_t uRegion, uint64_t *pu64LbaStart,
205	uint64_t pcBlocks, uint64_t pcbBlock,
206	PVDREGIONDATAFORM penmDataForm));
207
208	/**
209	* Queries the properties for the region covering the given LBA.
210	*
211	* @returns VBox status code.
212	* @retval VERR_NOT_FOUND if the region index is not known.
213	* @param hVScsiLun Virtual SCSI LUN handle.
214	* @param pvScsiLunUser Opaque user data which may be used to identify the
215	* medium.
216	* @param u64LbaStart Where to store the starting LBA for the region on success.
217	* @param puRegion Where to store the region number on success.
218	* @param pcBlocks Where to store the number of blocks left in this region starting from the given LBA.
219	* @param pcbBlock Where to store the size of one block in bytes on success.
220	* @param penmDataForm WHere to store the data form for the region on success.
221	*/
222	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumQueryRegionPropertiesForLba,(VSCSILUN hVScsiLun, void *pvScsiLunUser,
223	uint64_t u64LbaStart, uint32_t *puRegion,
224	uint64_t pcBlocks, uint64_t pcbBlock,
225	PVDREGIONDATAFORM penmDataForm));
226
227	/**
228	* Set the lock state of the underlying medium.
229	*
230	* @returns VBox status status code.
231	* @param hVScsiLun Virtual SCSI LUN handle.
232	* @param pvScsiLunUser Opaque user data which may be used to identify the
233	* medium.
234	* @param fLocked New lock state (locked/unlocked).
235	*/
236	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumSetLock,(VSCSILUN hVScsiLun, void *pvScsiLunUser, bool fLocked));
237
238	/**
239	* Eject the attached medium.
240	*
241	* @returns VBox status code.
242	* @param hVScsiLun Virtual SCSI LUN handle.
243	* @param pvScsiLunUser Opaque user data which may be used to identify the
244	* medium.
245	*/
246	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumEject, (VSCSILUN hVScsiLun, void *pvScsiLunUser));
247
248	/**
249	* Enqueue a read or write request from the medium.
250	*
251	* @returns VBox status status code.
252	* @param hVScsiLun Virtual SCSI LUN handle.
253	* @param pvScsiLunUser Opaque user data which may be used to identify the
254	* medium.
255	* @param hVScsiIoReq Virtual SCSI I/O request handle.
256	*/
257	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqTransferEnqueue,(VSCSILUN hVScsiLun, void *pvScsiLunUser, VSCSIIOREQ hVScsiIoReq));
258
259	/**
260	* Returns flags of supported features.
261	*
262	* @returns VBox status status code.
263	* @param hVScsiLun Virtual SCSI LUN handle.
264	* @param pvScsiLunUser Opaque user data which may be used to identify the
265	* medium.
266	* @param pfFeatures Where to return the queried features.
267	*/
268	DECLR3CALLBACKMEMBER(int, pfnVScsiLunGetFeatureFlags,(VSCSILUN hVScsiLun, void pvScsiLunUser, uint64_t pfFeatures));
269
270	/**
271	* Queries the vendor and product ID and revision to report for INQUIRY commands of the given LUN.
272	*
273	* @returns VBox status status code.
274	* @retval VERR_NOT_FOUND if the data is not available and some defaults should be sued instead.
275	* @param hVScsiLun Virtual SCSI LUN handle.
276	* @param pvScsiLunUser Opaque user data which may be used to identify the
277	* medium.
278	* @param ppszVendorId Where to store the pointer to the vendor ID string to report.
279	* @param ppszProductId Where to store the pointer to the product ID string to report.
280	* @param ppszProductLevel Where to store the pointer to the product level string to report.
281	*/
282	DECLR3CALLBACKMEMBER(int, pfnVScsiLunQueryInqStrings, (VSCSILUN hVScsiLun, void pvScsiLunUser, const char *ppszVendorId,
283	const char ppszProductId, const char ppszProductLevel));
284
285	} VSCSILUNIOCALLBACKS;
286	/** Pointer to a virtual SCSI LUN I/O callback table. */
287	typedef VSCSILUNIOCALLBACKS *PVSCSILUNIOCALLBACKS;
288
289	/**
290	* The virtual SCSI request completed callback.
291	*/
292	typedef DECLCALLBACKTYPE(void, FNVSCSIREQCOMPLETED,(VSCSIDEVICE hVScsiDevice,
293	void *pvVScsiDeviceUser,
294	void *pvVScsiReqUser,
295	int rcScsiCode,
296	bool fRedoPossible,
297	int rcReq,
298	size_t cbXfer,
299	VSCSIXFERDIR enmXferDir,
300	size_t cbSense));
301	/** Pointer to a virtual SCSI request completed callback. */
302	typedef FNVSCSIREQCOMPLETED *PFNVSCSIREQCOMPLETED;
303
304	/**
305	* Create a new empty SCSI device instance.
306	*
307	* @returns VBox status code.
308	* @param phVScsiDevice Where to store the SCSI device handle.
309	* @param pfnVScsiReqCompleted The method call after a request completed.
310	* @param pvVScsiDeviceUser Opaque user data given in the completion callback.
311	*/
312	VBOXDDU_DECL(int) VSCSIDeviceCreate(PVSCSIDEVICE phVScsiDevice,
313	PFNVSCSIREQCOMPLETED pfnVScsiReqCompleted,
314	void *pvVScsiDeviceUser);
315
316	/**
317	* Destroy a SCSI device instance.
318	*
319	* @returns VBox status code.
320	* @param hVScsiDevice The SCSI device handle to destroy.
321	*/
322	VBOXDDU_DECL(int) VSCSIDeviceDestroy(VSCSIDEVICE hVScsiDevice);
323
324	/**
325	* Attach a LUN to the SCSI device.
326	*
327	* @returns VBox status code.
328	* @param hVScsiDevice The SCSI device handle to add the LUN to.
329	* @param hVScsiLun The LUN handle to add.
330	* @param iLun The LUN number.
331	*/
332	VBOXDDU_DECL(int) VSCSIDeviceLunAttach(VSCSIDEVICE hVScsiDevice, VSCSILUN hVScsiLun, uint32_t iLun);
333
334	/**
335	* Detach a LUN from the SCSI device.
336	*
337	* @returns VBox status code.
338	* @param hVScsiDevice The SCSI device handle to add the LUN to.
339	* @param iLun The LUN number to remove.
340	* @param phVScsiLun Where to store the detached LUN handle.
341	*/
342	VBOXDDU_DECL(int) VSCSIDeviceLunDetach(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
343	PVSCSILUN phVScsiLun);
344
345	/**
346	* Query the SCSI LUN type.
347	*
348	* @returns VBox status code.
349	* @param hVScsiDevice The SCSI device handle.
350	* @param iLun The LUN number to get.
351	* @param pEnmLunType Where to store the LUN type.
352	*/
353	VBOXDDU_DECL(int) VSCSIDeviceLunQueryType(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
354	PVSCSILUNTYPE pEnmLunType);
355
356	/**
357	* Enqueue a request to the SCSI device.
358	*
359	* @returns VBox status code.
360	* @param hVScsiDevice The SCSI device handle.
361	* @param hVScsiReq The SCSI request handle to enqueue.
362	*/
363	VBOXDDU_DECL(int) VSCSIDeviceReqEnqueue(VSCSIDEVICE hVScsiDevice, VSCSIREQ hVScsiReq);
364
365	/**
366	* Allocate a new request handle.
367	*
368	* @returns VBox status code.
369	* @param hVScsiDevice The SCSI device handle.
370	* @param phVScsiReq Where to SCSI request handle.
371	* @param iLun The LUN the request is for.
372	* @param pbCDB The CDB for the request.
373	* @param cbCDB The size of the CDB in bytes.
374	* @param cbSGList Number of bytes the S/G list describes.
375	* @param cSGListEntries Number of S/G list entries.
376	* @param paSGList Pointer to the S/G list.
377	* @param pbSense Pointer to the sense buffer.
378	* @param cbSense Size of the sense buffer.
379	* @param pvVScsiReqUser Opqaue user data returned when the request completes.
380	*/
381	VBOXDDU_DECL(int) VSCSIDeviceReqCreate(VSCSIDEVICE hVScsiDevice, PVSCSIREQ phVScsiReq,
382	uint32_t iLun, uint8_t *pbCDB, size_t cbCDB,
383	size_t cbSGList, unsigned cSGListEntries,
384	PCRTSGSEG paSGList, uint8_t *pbSense,
385	size_t cbSense, void *pvVScsiReqUser);
386
387	/**
388	* Create a new LUN.
389	*
390	* @returns VBox status code.
391	* @param phVScsiLun Where to store the SCSI LUN handle.
392	* @param enmLunType The Lun type.
393	* @param pVScsiLunIoCallbacks Pointer to the I/O callbacks to use for his LUN.
394	* @param pvVScsiLunUser Opaque user argument which
395	* is returned in the pvScsiLunUser parameter
396	* when the request completion callback is called.
397	*/
398	VBOXDDU_DECL(int) VSCSILunCreate(PVSCSILUN phVScsiLun, VSCSILUNTYPE enmLunType,
399	PVSCSILUNIOCALLBACKS pVScsiLunIoCallbacks,
400	void *pvVScsiLunUser);
401
402	/**
403	* Destroy virtual SCSI LUN.
404	*
405	* @returns VBox status code.
406	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
407	*/
408	VBOXDDU_DECL(int) VSCSILunDestroy(VSCSILUN hVScsiLun);
409
410	/**
411	* Notify virtual SCSI LUN of medium being mounted.
412	*
413	* @returns VBox status code.
414	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
415	*/
416	VBOXDDU_DECL(int) VSCSILunMountNotify(VSCSILUN hVScsiLun);
417
418	/**
419	* Notify virtual SCSI LUN of medium being unmounted.
420	*
421	* @returns VBox status code.
422	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
423	*/
424	VBOXDDU_DECL(int) VSCSILunUnmountNotify(VSCSILUN hVScsiLun);
425
426	/**
427	* Notify a that a I/O request completed.
428	*
429	* @returns VBox status code.
430	* @param hVScsiIoReq The I/O request handle that completed.
431	* This is given when a I/O callback for
432	* the LUN is called by the virtual SCSI layer.
433	* @param rcIoReq The status code the I/O request completed with.
434	* @param fRedoPossible Flag whether it is possible to redo the request.
435	* If true setting any sense code will be omitted
436	* in case of an error to not alter the device state.
437	*/
438	VBOXDDU_DECL(int) VSCSIIoReqCompleted(VSCSIIOREQ hVScsiIoReq, int rcIoReq, bool fRedoPossible);
439
440	/**
441	* Query the transfer direction of the I/O request.
442	*
443	* @returns Transfer direction.of the given I/O request
444	* @param hVScsiIoReq The SCSI I/O request handle.
445	*/
446	VBOXDDU_DECL(VSCSIIOREQTXDIR) VSCSIIoReqTxDirGet(VSCSIIOREQ hVScsiIoReq);
447
448	/**
449	* Query I/O parameters.
450	*
451	* @returns VBox status code.
452	* @param hVScsiIoReq The SCSI I/O request handle.
453	* @param puOffset Where to store the start offset.
454	* @param pcbTransfer Where to store the amount of bytes to transfer.
455	* @param pcSeg Where to store the number of segments in the S/G list.
456	* @param pcbSeg Where to store the number of bytes the S/G list describes.
457	* @param ppaSeg Where to store the pointer to the S/G list.
458	*/
459	VBOXDDU_DECL(int) VSCSIIoReqParamsGet(VSCSIIOREQ hVScsiIoReq, uint64_t *puOffset,
460	size_t pcbTransfer, unsigned pcSeg,
461	size_t pcbSeg, PCRTSGSEG ppaSeg);
462
463	/**
464	* Query unmap parameters.
465	*
466	* @returns VBox status code.
467	* @param hVScsiIoReq The SCSI I/O request handle.
468	* @param ppaRanges Where to store the pointer to the range array on success.
469	* @param pcRanges Where to store the number of ranges on success.
470	*/
471	VBOXDDU_DECL(int) VSCSIIoReqUnmapParamsGet(VSCSIIOREQ hVScsiIoReq, PCRTRANGE *ppaRanges,
472	unsigned *pcRanges);
473
474	/** @} */
475	RT_C_DECLS_END
476
477	#endif /* !VBOX_INCLUDED_vscsi_h */
478

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

source: vbox/trunk/include/VBox/vscsi.h@ 89363

Download in other formats: