vscsi.h@ 64622

Last change on this file since 64622 was 64274, checked in by vboxsync, 8 years ago
Devices/Storage: Doxygen fixes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 15.3 KB

Line
1	/* $Id: vscsi.h 64274 2016-10-14 10:33:43Z vboxsync $ */
2	/** @file
3	* VBox storage drivers - Virtual SCSI driver
4	*/
5
6	/*
7	* Copyright (C) 2006-2016 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_vscsi_h
28	#define ___VBox_vscsi_h
29
30	#include <VBox/cdefs.h>
31	#include <VBox/types.h>
32	#include <iprt/sg.h>
33
34	RT_C_DECLS_BEGIN
35
36	#ifdef IN_RING0
37	# error "There are no VBox VSCSI APIs available in Ring-0 Host Context!"
38	#endif
39
40	/** @defgroup grp_drv_vscsi Virtual VSCSI Driver
41	* @ingroup grp_devdrv
42	* @{
43	*/
44	/** @todo figure better grouping. */
45
46	/** A virtual SCSI device handle */
47	typedef struct VSCSIDEVICEINT *VSCSIDEVICE;
48	/** A pointer to a virtual SCSI device handle. */
49	typedef VSCSIDEVICE *PVSCSIDEVICE;
50	/** A virtual SCSI LUN handle. */
51	typedef struct VSCSILUNINT *VSCSILUN;
52	/** A pointer to a virtual SCSI LUN handle. */
53	typedef VSCSILUN *PVSCSILUN;
54	/** A virtual SCSI request handle. */
55	typedef struct VSCSIREQINT *VSCSIREQ;
56	/** A pointer to a virtual SCSI request handle. */
57	typedef VSCSIREQ *PVSCSIREQ;
58	/** A SCSI I/O request handle. */
59	typedef struct VSCSIIOREQINT *VSCSIIOREQ;
60	/** A pointer to a SCSI I/O request handle. */
61	typedef VSCSIIOREQ *PVSCSIIOREQ;
62
63	/**
64	* Virtual SCSI I/O request transfer direction.
65	*/
66	typedef enum VSCSIIOREQTXDIR
67	{
68	/** Invalid direction */
69	VSCSIIOREQTXDIR_INVALID = 0,
70	/** Read */
71	VSCSIIOREQTXDIR_READ,
72	/** Write */
73	VSCSIIOREQTXDIR_WRITE,
74	/** Flush */
75	VSCSIIOREQTXDIR_FLUSH,
76	/** Unmap */
77	VSCSIIOREQTXDIR_UNMAP,
78	/** 32bit hack */
79	VSCSIIOREQTXDIR_32BIT_HACK = 0x7fffffff
80	} VSCSIIOREQTXDIR;
81	/** Pointer to a SCSI LUN type */
82	typedef VSCSIIOREQTXDIR *PVSCSIIOREQTXDIR;
83
84	/**
85	* LUN types we support
86	*/
87	typedef enum VSCSILUNTYPE
88	{
89	/** Invalid type */
90	VSCSILUNTYPE_INVALID = 0,
91	/** Hard disk (SBC) */
92	VSCSILUNTYPE_SBC,
93	/** CD/DVD drive (MMC) */
94	VSCSILUNTYPE_MMC,
95	/** Tape drive (SSC) */
96	VSCSILUNTYPE_SSC,
97	/** Last value to indicate an invalid device */
98	VSCSILUNTYPE_LAST,
99	/** 32bit hack */
100	VSCSILUNTYPE_32BIT_HACK = 0x7fffffff
101	} VSCSILUNTYPE;
102	/** Pointer to a SCSI LUN type */
103	typedef VSCSILUNTYPE *PVSCSILUNTYPE;
104
105	/** The LUN can handle the UNMAP command. */
106	#define VSCSI_LUN_FEATURE_UNMAP RT_BIT(0)
107	/** The LUN has a non rotational medium. */
108	#define VSCSI_LUN_FEATURE_NON_ROTATIONAL RT_BIT(1)
109	/** The medium of the LUN is readonly. */
110	#define VSCSI_LUN_FEATURE_READONLY RT_BIT(2)
111
112	/**
113	* Virtual SCSI LUN I/O Callback table.
114	*/
115	typedef struct VSCSILUNIOCALLBACKS
116	{
117	/**
118	* Sets the size of the allocator specific memory for a I/O request.
119	*
120	* @returns VBox status code.
121	* @param hVScsiLun Virtual SCSI LUN handle.
122	* @param pvScsiLunUser Opaque user data which may be used to identify the
123	* medium.
124	* @param cbVScsiIoReqAlloc The size of the allocator specific memory in bytes.
125	* @thread EMT.
126	*/
127	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqAllocSizeSet, (VSCSILUN hVScsiLun, void *pvScsiLunUser,
128	size_t cbVScsiIoReqAlloc));
129
130	/**
131	* Allocates a new I/O request.
132	*
133	* @returns VBox status code.
134	* @param hVScsiLun Virtual SCSI LUN handle.
135	* @param pvScsiLunUser Opaque user data which may be used to identify the
136	* medium.
137	* @param u64Tag A tag to assign to the request handle for identification later on.
138	* @param phVScsiIoReq Where to store the handle to the allocated I/O request on success.
139	* @thread Any thread.
140	*/
141	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqAlloc, (VSCSILUN hVScsiLun, void *pvScsiLunUser,
142	uint64_t u64Tag, PVSCSIIOREQ phVScsiIoReq));
143
144	/**
145	* Frees a given I/O request.
146	*
147	* @returns VBox status code.
148	* @param hVScsiLun Virtual SCSI LUN handle.
149	* @param pvScsiLunUser Opaque user data which may be used to identify the
150	* medium.
151	* @param hVScsiIoReq The VSCSI I/O request to free.
152	* @thread Any thread.
153	*/
154	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqFree, (VSCSILUN hVScsiLun, void *pvScsiLunUser, VSCSIIOREQ hVScsiIoReq));
155
156	/**
157	* Retrieve the size of the underlying medium.
158	*
159	* @returns VBox status status code.
160	* @param hVScsiLun Virtual SCSI LUN handle.
161	* @param pvScsiLunUser Opaque user data which may be used to identify the
162	* medium.
163	* @param pcbSize Where to store the size of the medium.
164	*/
165	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumGetSize,(VSCSILUN hVScsiLun, void pvScsiLunUser, uint64_t pcbSize));
166
167	/**
168	* Retrieve the sector size of the underlying medium.
169	*
170	* @returns VBox status 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 pcbSectorSize Where to store the sector size of the medium.
175	*/
176	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumGetSectorSize,(VSCSILUN hVScsiLun, void pvScsiLunUser, uint32_t pcbSectorSize));
177
178	/**
179	* Set the lock state of the underlying medium.
180	*
181	* @returns VBox status status code.
182	* @param hVScsiLun Virtual SCSI LUN handle.
183	* @param pvScsiLunUser Opaque user data which may be used to identify the
184	* medium.
185	* @param fLocked New lock state (locked/unlocked).
186	*/
187	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumSetLock,(VSCSILUN hVScsiLun, void *pvScsiLunUser, bool fLocked));
188
189	/**
190	* Eject the attached medium.
191	*
192	* @returns VBox status code.
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(int, pfnVScsiLunMediumEject, (VSCSILUN hVScsiLun, void *pvScsiLunUser));
198
199	/**
200	* Enqueue a read or write request from the medium.
201	*
202	* @returns VBox status status code.
203	* @param hVScsiLun Virtual SCSI LUN handle.
204	* @param pvScsiLunUser Opaque user data which may be used to identify the
205	* medium.
206	* @param hVScsiIoReq Virtual SCSI I/O request handle.
207	*/
208	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqTransferEnqueue,(VSCSILUN hVScsiLun, void *pvScsiLunUser, VSCSIIOREQ hVScsiIoReq));
209
210	/**
211	* Returns flags of supported features.
212	*
213	* @returns VBox status status code.
214	* @param hVScsiLun Virtual SCSI LUN handle.
215	* @param pvScsiLunUser Opaque user data which may be used to identify the
216	* medium.
217	* @param pfFeatures Where to return the queried features.
218	*/
219	DECLR3CALLBACKMEMBER(int, pfnVScsiLunGetFeatureFlags,(VSCSILUN hVScsiLun, void pvScsiLunUser, uint64_t pfFeatures));
220
221	} VSCSILUNIOCALLBACKS;
222	/** Pointer to a virtual SCSI LUN I/O callback table. */
223	typedef VSCSILUNIOCALLBACKS *PVSCSILUNIOCALLBACKS;
224
225	/**
226	* The virtual SCSI request completed callback.
227	*/
228	typedef DECLCALLBACK(void) FNVSCSIREQCOMPLETED(VSCSIDEVICE hVScsiDevice,
229	void *pvVScsiDeviceUser,
230	void *pvVScsiReqUser,
231	int rcScsiCode,
232	bool fRedoPossible,
233	int rcReq);
234	/** Pointer to a virtual SCSI request completed callback. */
235	typedef FNVSCSIREQCOMPLETED *PFNVSCSIREQCOMPLETED;
236
237	/**
238	* Create a new empty SCSI device instance.
239	*
240	* @returns VBox status code.
241	* @param phVScsiDevice Where to store the SCSI device handle.
242	* @param pfnVScsiReqCompleted The method call after a request completed.
243	* @param pvVScsiDeviceUser Opaque user data given in the completion callback.
244	*/
245	VBOXDDU_DECL(int) VSCSIDeviceCreate(PVSCSIDEVICE phVScsiDevice,
246	PFNVSCSIREQCOMPLETED pfnVScsiReqCompleted,
247	void *pvVScsiDeviceUser);
248
249	/**
250	* Destroy a SCSI device instance.
251	*
252	* @returns VBox status code.
253	* @param hVScsiDevice The SCSI device handle to destroy.
254	*/
255	VBOXDDU_DECL(int) VSCSIDeviceDestroy(VSCSIDEVICE hVScsiDevice);
256
257	/**
258	* Attach a LUN to the SCSI device.
259	*
260	* @returns VBox status code.
261	* @param hVScsiDevice The SCSI device handle to add the LUN to.
262	* @param hVScsiLun The LUN handle to add.
263	* @param iLun The LUN number.
264	*/
265	VBOXDDU_DECL(int) VSCSIDeviceLunAttach(VSCSIDEVICE hVScsiDevice, VSCSILUN hVScsiLun, uint32_t iLun);
266
267	/**
268	* Detach a LUN from the SCSI device.
269	*
270	* @returns VBox status code.
271	* @param hVScsiDevice The SCSI device handle to add the LUN to.
272	* @param iLun The LUN number to remove.
273	* @param phVScsiLun Where to store the detached LUN handle.
274	*/
275	VBOXDDU_DECL(int) VSCSIDeviceLunDetach(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
276	PVSCSILUN phVScsiLun);
277
278	/**
279	* Query the SCSI LUN type.
280	*
281	* @returns VBox status code.
282	* @param hVScsiDevice The SCSI device handle.
283	* @param iLun The LUN number to get.
284	* @param pEnmLunType Where to store the LUN type.
285	*/
286	VBOXDDU_DECL(int) VSCSIDeviceLunQueryType(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
287	PVSCSILUNTYPE pEnmLunType);
288
289	/**
290	* Enqueue a request to the SCSI device.
291	*
292	* @returns VBox status code.
293	* @param hVScsiDevice The SCSI device handle.
294	* @param hVScsiReq The SCSI request handle to enqueue.
295	*/
296	VBOXDDU_DECL(int) VSCSIDeviceReqEnqueue(VSCSIDEVICE hVScsiDevice, VSCSIREQ hVScsiReq);
297
298	/**
299	* Allocate a new request handle.
300	*
301	* @returns VBox status code.
302	* @param hVScsiDevice The SCSI device handle.
303	* @param phVScsiReq Where to SCSI request handle.
304	* @param iLun The LUN the request is for.
305	* @param pbCDB The CDB for the request.
306	* @param cbCDB The size of the CDB in bytes.
307	* @param cbSGList Number of bytes the S/G list describes.
308	* @param cSGListEntries Number of S/G list entries.
309	* @param paSGList Pointer to the S/G list.
310	* @param pbSense Pointer to the sense buffer.
311	* @param cbSense Size of the sense buffer.
312	* @param pvVScsiReqUser Opqaue user data returned when the request completes.
313	*/
314	VBOXDDU_DECL(int) VSCSIDeviceReqCreate(VSCSIDEVICE hVScsiDevice, PVSCSIREQ phVScsiReq,
315	uint32_t iLun, uint8_t *pbCDB, size_t cbCDB,
316	size_t cbSGList, unsigned cSGListEntries,
317	PCRTSGSEG paSGList, uint8_t *pbSense,
318	size_t cbSense, void *pvVScsiReqUser);
319
320	/**
321	* Create a new LUN.
322	*
323	* @returns VBox status code.
324	* @param phVScsiLun Where to store the SCSI LUN handle.
325	* @param enmLunType The Lun type.
326	* @param pVScsiLunIoCallbacks Pointer to the I/O callbacks to use for his LUN.
327	* @param pvVScsiLunUser Opaque user argument which
328	* is returned in the pvScsiLunUser parameter
329	* when the request completion callback is called.
330	*/
331	VBOXDDU_DECL(int) VSCSILunCreate(PVSCSILUN phVScsiLun, VSCSILUNTYPE enmLunType,
332	PVSCSILUNIOCALLBACKS pVScsiLunIoCallbacks,
333	void *pvVScsiLunUser);
334
335	/**
336	* Destroy virtual SCSI LUN.
337	*
338	* @returns VBox status code.
339	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
340	*/
341	VBOXDDU_DECL(int) VSCSILunDestroy(VSCSILUN hVScsiLun);
342
343	/**
344	* Notify virtual SCSI LUN of medium being mounted.
345	*
346	* @returns VBox status code.
347	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
348	*/
349	VBOXDDU_DECL(int) VSCSILunMountNotify(VSCSILUN hVScsiLun);
350
351	/**
352	* Notify virtual SCSI LUN of medium being unmounted.
353	*
354	* @returns VBox status code.
355	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
356	*/
357	VBOXDDU_DECL(int) VSCSILunUnmountNotify(VSCSILUN hVScsiLun);
358
359	/**
360	* Notify a that a I/O request completed.
361	*
362	* @returns VBox status code.
363	* @param hVScsiIoReq The I/O request handle that completed.
364	* This is given when a I/O callback for
365	* the LUN is called by the virtual SCSI layer.
366	* @param rcIoReq The status code the I/O request completed with.
367	* @param fRedoPossible Flag whether it is possible to redo the request.
368	* If true setting any sense code will be omitted
369	* in case of an error to not alter the device state.
370	*/
371	VBOXDDU_DECL(int) VSCSIIoReqCompleted(VSCSIIOREQ hVScsiIoReq, int rcIoReq, bool fRedoPossible);
372
373	/**
374	* Query the transfer direction of the I/O request.
375	*
376	* @returns Transfer direction.of the given I/O request
377	* @param hVScsiIoReq The SCSI I/O request handle.
378	*/
379	VBOXDDU_DECL(VSCSIIOREQTXDIR) VSCSIIoReqTxDirGet(VSCSIIOREQ hVScsiIoReq);
380
381	/**
382	* Query I/O parameters.
383	*
384	* @returns VBox status code.
385	* @param hVScsiIoReq The SCSI I/O request handle.
386	* @param puOffset Where to store the start offset.
387	* @param pcbTransfer Where to store the amount of bytes to transfer.
388	* @param pcSeg Where to store the number of segments in the S/G list.
389	* @param pcbSeg Where to store the number of bytes the S/G list describes.
390	* @param ppaSeg Where to store the pointer to the S/G list.
391	*/
392	VBOXDDU_DECL(int) VSCSIIoReqParamsGet(VSCSIIOREQ hVScsiIoReq, uint64_t *puOffset,
393	size_t pcbTransfer, unsigned pcSeg,
394	size_t pcbSeg, PCRTSGSEG ppaSeg);
395
396	/**
397	* Query unmap parameters.
398	*
399	* @returns VBox status code.
400	* @param hVScsiIoReq The SCSI I/O request handle.
401	* @param ppaRanges Where to store the pointer to the range array on success.
402	* @param pcRanges Where to store the number of ranges on success.
403	*/
404	VBOXDDU_DECL(int) VSCSIIoReqUnmapParamsGet(VSCSIIOREQ hVScsiIoReq, PCRTRANGE *ppaRanges,
405	unsigned *pcRanges);
406
407	/** @} */
408	RT_C_DECLS_END
409
410	#endif /* ___VBox_vscsi_h */
411

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

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

Download in other formats: