vscsi.h@ 106165

Last change on this file since 106165 was 106061, checked in by vboxsync, 2 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 19.3 KB

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

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

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

Download in other formats: