VirtualBox

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

Last change on this file since 36882 was 33540, checked in by vboxsync, 14 years ago

*: spelling fixes, thanks Timeless!

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.7 KB
Line 
1/* $Id: vscsi.h 33540 2010-10-28 09:27:05Z vboxsync $ */
2/** @file
3 * VBox storage drivers: Virtual SCSI driver
4 */
5
6/*
7 * Copyright (C) 2006-2010 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
34RT_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/** A virtual SCSI device handle */
41typedef struct VSCSIDEVICEINT *VSCSIDEVICE;
42/** A pointer to a virtual SCSI device handle. */
43typedef VSCSIDEVICE *PVSCSIDEVICE;
44/** A virtual SCSI LUN handle. */
45typedef struct VSCSILUNINT *VSCSILUN;
46/** A pointer to a virtual SCSI LUN handle. */
47typedef VSCSILUN *PVSCSILUN;
48/** A virtual SCSI request handle. */
49typedef struct VSCSIREQINT *VSCSIREQ;
50/** A pointer to a virtual SCSI request handle. */
51typedef VSCSIREQ *PVSCSIREQ;
52/** A SCSI I/O request handle. */
53typedef struct VSCSIIOREQINT *VSCSIIOREQ;
54/** A pointer to a SCSI I/O request handle. */
55typedef VSCSIIOREQ *PVSCSIIOREQ;
56
57/**
58 * Virtual SCSI I/O request transfer direction.
59 */
60typedef enum VSCSIIOREQTXDIR
61{
62 /** Invalid direction */
63 VSCSIIOREQTXDIR_INVALID = 0,
64 /** Read */
65 VSCSIIOREQTXDIR_READ,
66 /** Write */
67 VSCSIIOREQTXDIR_WRITE,
68 /** Flush */
69 VSCSIIOREQTXDIR_FLUSH,
70 /** 32bit hack */
71 VSCSIIOREQTXDIR_32BIT_HACK = 0x7fffffff
72} VSCSIIOREQTXDIR;
73/** Pointer to a SCSI LUN type */
74typedef VSCSIIOREQTXDIR *PVSCSIIOREQTXDIR;
75
76/**
77 * LUN types we support
78 */
79typedef enum VSCSILUNTYPE
80{
81 /** Invalid type */
82 VSCSILUNTYPE_INVALID = 0,
83 /** Hard disk (SBC) */
84 VSCSILUNTYPE_SBC,
85 /** CD/DVD drive (MMC) */
86 VSCSILUNTYPE_MMC,
87 /** Last value to indicate an invalid device */
88 VSCSILUNTYPE_LAST,
89 /** 32bit hack */
90 VSCSILUNTYPE_32BIT_HACK = 0x7fffffff
91} VSCSILUNTYPE;
92/** Pointer to a SCSI LUN type */
93typedef VSCSILUNTYPE *PVSCSILUNTYPE;
94
95/**
96 * Virtual SCSI LUN I/O Callback table.
97 */
98typedef struct VSCSILUNIOCALLBACKS
99{
100 /**
101 * Retrieve the size of the underlying medium.
102 *
103 * @returns VBox status status code.
104 * @param hVScsiLun Virtual SCSI LUN handle.
105 * @param pvScsiLunUser Opaque user data which may
106 * be used to identify the medium.
107 * @param pcbSize Where to store the size of the
108 * medium.
109 */
110 DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumGetSize, (VSCSILUN hVScsiLun,
111 void *pvScsiLunUser,
112 uint64_t *pcbSize));
113
114 /**
115 * Enqueue a read or write request from the medium.
116 *
117 * @returns VBox status status code.
118 * @param hVScsiLun Virtual SCSI LUN handle.
119 * @param pvScsiLunUser Opaque user data which may
120 * be used to identify the medium.
121 * @param hVScsiIoReq Virtual SCSI I/O request handle.
122 */
123 DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqTransferEnqueue, (VSCSILUN hVScsiLun,
124 void *pvScsiLunUser,
125 VSCSIIOREQ hVScsiIoReq));
126
127} VSCSILUNIOCALLBACKS;
128/** Pointer to a virtual SCSI LUN I/O callback table. */
129typedef VSCSILUNIOCALLBACKS *PVSCSILUNIOCALLBACKS;
130
131/**
132 * The virtual SCSI request completed callback.
133 */
134typedef DECLCALLBACK(void) FNVSCSIREQCOMPLETED(VSCSIDEVICE hVScsiDevice,
135 void *pvVScsiDeviceUser,
136 void *pvVScsiReqUser,
137 int rcScsiCode,
138 bool fRedoPossible,
139 int rcReq);
140/** Pointer to a virtual SCSI request completed callback. */
141typedef FNVSCSIREQCOMPLETED *PFNVSCSIREQCOMPLETED;
142
143/**
144 * Create a new empty SCSI device instance.
145 *
146 * @returns VBox status code.
147 * @param phVScsiDevice Where to store the SCSI device handle.
148 * @param pfnVScsiReqCompleted The method call after a request completed.
149 * @param pvVScsiDeviceUser Opaque user data given in the completion callback.
150 */
151VBOXDDU_DECL(int) VSCSIDeviceCreate(PVSCSIDEVICE phVScsiDevice,
152 PFNVSCSIREQCOMPLETED pfnVScsiReqCompleted,
153 void *pvVScsiDeviceUser);
154
155/**
156 * Destroy a SCSI device instance.
157 *
158 * @returns VBox status code.
159 * @param hScsiDevice The SCSI device handle to destroy.
160 */
161VBOXDDU_DECL(int) VSCSIDeviceDestroy(VSCSIDEVICE hVScsiDevice);
162
163/**
164 * Attach a LUN to the SCSI device.
165 *
166 * @returns VBox status code.
167 * @param hScsiDevice The SCSI device handle to add the LUN to.
168 * @param hScsiLun The LUN handle to add.
169 * @param iLun The LUN number.
170 */
171VBOXDDU_DECL(int) VSCSIDeviceLunAttach(VSCSIDEVICE hVScsiDevice, VSCSILUN hVScsiLun, uint32_t iLun);
172
173/**
174 * Detach a LUN from the SCSI device.
175 *
176 * @returns VBox status code.
177 * @param hVScsiDevice The SCSI device handle to add the LUN to.
178 * @param iLun The LUN number to remove.
179 * @param phVScsiLun Where to store the detached LUN handle.
180 */
181VBOXDDU_DECL(int) VSCSIDeviceLunDetach(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
182 PVSCSILUN phVScsiLun);
183
184/**
185 * Return the SCSI LUN handle.
186 *
187 * @returns VBox status code.
188 * @param hVScsiDevice The SCSI device handle.
189 * @param iLun The LUN number to get.
190 * @param phVScsiLun Where to store the LUN handle.
191 */
192VBOXDDU_DECL(int) VSCSIDeviceLunGet(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
193 PVSCSILUN phVScsiLun);
194
195/**
196 * Enqueue a request to the SCSI device.
197 *
198 * @returns VBox status code.
199 * @param hVScsiDevice The SCSI device handle.
200 * @param hVScsiReq The SCSI request handle to enqueue.
201 */
202VBOXDDU_DECL(int) VSCSIDeviceReqEnqueue(VSCSIDEVICE hVScsiDevice, VSCSIREQ hVScsiReq);
203
204/**
205 * Allocate a new request handle.
206 *
207 * @returns VBox status code.
208 * @param phVScsiDevice The SCSI device handle.
209 * @param phVScsiReq Where to SCSI request handle.
210 * @param iLun The LUN the request is for.
211 * @param pbCDB The CDB for the request.
212 * @param cbCDB The size of the CDB in bytes.
213 * @param cbSGList Number of bytes the S/G list describes.
214 * @param cSGListEntries Number of S/G list entries.
215 * @param paSGList Pointer to the S/G list.
216 * @param pbSense Pointer to the sense buffer.
217 * @param cbSense Size of the sense buffer.
218 * @param pvVScsiReqUser Opqaue user data returned when the request completes.
219 */
220VBOXDDU_DECL(int) VSCSIDeviceReqCreate(VSCSIDEVICE hVScsiDevice, PVSCSIREQ phVScsiReq,
221 uint32_t iLun, uint8_t *pbCDB, size_t cbCDB,
222 size_t cbSGList, unsigned cSGListEntries,
223 PCRTSGSEG paSGList, uint8_t *pbSense,
224 size_t cbSense, void *pvVScsiReqUser);
225
226/**
227 * Create a new LUN.
228 *
229 * @returns VBox status code.
230 * @param phVScsiLun Where to store the SCSI LUN handle.
231 * @param enmLunType The Lun type.
232 * @param pVScsiLunIoCallbacks Pointer to the I/O callbacks to use for his LUN.
233 * @param pvVScsiLunUser Opaque user argument which
234 * is returned in the pvScsiLunUser parameter
235 * when the request completion callback is called.
236 */
237VBOXDDU_DECL(int) VSCSILunCreate(PVSCSILUN phVScsiLun, VSCSILUNTYPE enmLunType,
238 PVSCSILUNIOCALLBACKS pVScsiLunIoCallbacks,
239 void *pvVScsiLunUser);
240
241/**
242 * Destroy virtual SCSI LUN.
243 *
244 * @returns VBox status code.
245 * @param hVScsiLun The virtual SCSI LUN handle to destroy.
246 */
247VBOXDDU_DECL(int) VSCSILunDestroy(VSCSILUN hVScsiLun);
248
249/**
250 * Notify a that a I/O request completed.
251 *
252 * @returns VBox status code.
253 * @param hVScsiIoReq The I/O request handle that completed.
254 * This is given when a I/O callback for
255 * the LUN is called by the virtual SCSI layer.
256 * @param rcIoReq The status code the I/O request completed with.
257 * @param fRedoPossible Flag whether it is possible to redo the request.
258 * If true setting any sense code will be omitted
259 * in case of an error to not alter the device state.
260 */
261VBOXDDU_DECL(int) VSCSIIoReqCompleted(VSCSIIOREQ hVScsiIoReq, int rcIoReq, bool fRedoPossible);
262
263/**
264 * Query the transfer direction of the I/O request.
265 *
266 * @returns Transfer direction.of the given I/O request
267 * @param hVScsiIoReq The SCSI I/O request handle.
268 */
269VBOXDDU_DECL(VSCSIIOREQTXDIR) VSCSIIoReqTxDirGet(VSCSIIOREQ hVScsiIoReq);
270
271/**
272 * Query I/O parameters.
273 *
274 * @returns VBox status code.
275 * @param hVScsiIoReq The SCSI I/O request handle.
276 * @param puOffset Where to store the start offset.
277 * @param pcbTransfer Where to store the amount of bytes to transfer.
278 * @param pcSeg Where to store the number of segments in the S/G list.
279 * @param pcbSeg Where to store the number of bytes the S/G list describes.
280 * @param ppaSeg Where to store the pointer to the S/G list.
281 */
282VBOXDDU_DECL(int) VSCSIIoReqParamsGet(VSCSIIOREQ hVScsiIoReq, uint64_t *puOffset,
283 size_t *pcbTransfer, unsigned *pcSeg,
284 size_t *pcbSeg, PCRTSGSEG *ppaSeg);
285
286RT_C_DECLS_END
287
288#endif /* ___VBox_vscsi_h */
289
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette