vscsi.h@ 52664

Last change on this file since 52664 was 47830, checked in by vboxsync, 11 years ago
Devices/Storage: Missing changes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 13.7 KB

Rev	Line
[27653]	1	/* $Id: vscsi.h 47830 2013-08-18 12:33:32Z vboxsync $ */
	2	/** @file
	3	* VBox storage drivers: Virtual SCSI driver
	4	*/
	5
	6	/*
[44528]	7	* Copyright (C) 2006-2012 Oracle Corporation
[27653]	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	*
[27901]	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.
[27653]	25	*/
	26
	27	#ifndef ___VBox_vscsi_h
	28	#define ___VBox_vscsi_h
	29
	30	#include <VBox/cdefs.h>
	31	#include <VBox/types.h>
[28065]	32	#include <iprt/sg.h>
[27653]	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	/** A virtual SCSI device handle */
	41	typedef struct VSCSIDEVICEINT *VSCSIDEVICE;
	42	/** A pointer to a virtual SCSI device handle. */
	43	typedef VSCSIDEVICE *PVSCSIDEVICE;
	44	/** A virtual SCSI LUN handle. */
	45	typedef struct VSCSILUNINT *VSCSILUN;
	46	/** A pointer to a virtual SCSI LUN handle. */
	47	typedef VSCSILUN *PVSCSILUN;
	48	/** A virtual SCSI request handle. */
	49	typedef struct VSCSIREQINT *VSCSIREQ;
	50	/** A pointer to a virtual SCSI request handle. */
	51	typedef VSCSIREQ *PVSCSIREQ;
	52	/** A SCSI I/O request handle. */
	53	typedef struct VSCSIIOREQINT *VSCSIIOREQ;
	54	/** A pointer to a SCSI I/O request handle. */
	55	typedef VSCSIIOREQ *PVSCSIIOREQ;
	56
	57	/**
	58	* Virtual SCSI I/O request transfer direction.
	59	*/
	60	typedef 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,
[38680]	70	/** Unmap */
	71	VSCSIIOREQTXDIR_UNMAP,
[27653]	72	/** 32bit hack */
	73	VSCSIIOREQTXDIR_32BIT_HACK = 0x7fffffff
	74	} VSCSIIOREQTXDIR;
	75	/** Pointer to a SCSI LUN type */
	76	typedef VSCSIIOREQTXDIR *PVSCSIIOREQTXDIR;
	77
	78	/**
	79	* LUN types we support
	80	*/
	81	typedef enum VSCSILUNTYPE
	82	{
	83	/** Invalid type */
	84	VSCSILUNTYPE_INVALID = 0,
	85	/** Hard disk (SBC) */
	86	VSCSILUNTYPE_SBC,
	87	/** CD/DVD drive (MMC) */
	88	VSCSILUNTYPE_MMC,
	89	/** Last value to indicate an invalid device */
	90	VSCSILUNTYPE_LAST,
	91	/** 32bit hack */
	92	VSCSILUNTYPE_32BIT_HACK = 0x7fffffff
	93	} VSCSILUNTYPE;
	94	/** Pointer to a SCSI LUN type */
	95	typedef VSCSILUNTYPE *PVSCSILUNTYPE;
	96
[38680]	97	/** The LUN can handle the UNMAP command. */
	98	#define VSCSI_LUN_FEATURE_UNMAP RT_BIT(0)
	99	/** The LUN has a non rotational medium. */
	100	#define VSCSI_LUN_FEATURE_NON_ROTATIONAL RT_BIT(1)
[39566]	101	/** The medium of the LUN is readonly. */
	102	#define VSCSI_LUN_FEATURE_READONLY RT_BIT(2)
[38680]	103
	104	/**
[27653]	105	* Virtual SCSI LUN I/O Callback table.
	106	*/
	107	typedef struct VSCSILUNIOCALLBACKS
	108	{
	109	/**
	110	* Retrieve the size of the underlying medium.
	111	*
	112	* @returns VBox status status code.
	113	* @param hVScsiLun Virtual SCSI LUN handle.
	114	* @param pvScsiLunUser Opaque user data which may
	115	* be used to identify the medium.
	116	* @param pcbSize Where to store the size of the
	117	* medium.
	118	*/
	119	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumGetSize, (VSCSILUN hVScsiLun,
	120	void *pvScsiLunUser,
	121	uint64_t *pcbSize));
	122
	123	/**
[47830]	124	* Retrieve the sector size of the underlying medium.
	125	*
	126	* @returns VBox status status code.
	127	* @param hVScsiLun Virtual SCSI LUN handle.
	128	* @param pvScsiLunUser Opaque user data which may
	129	* be used to identify the medium.
	130	* @param pcbSectorSize Where to store the sector size of the
	131	* medium.
	132	*/
	133	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumGetSectorSize, (VSCSILUN hVScsiLun,
	134	void *pvScsiLunUser,
	135	uint32_t *pcbSectorSize));
	136
	137	/**
[43694]	138	* Set the lock state of the underlying medium.
	139	*
	140	* @returns VBox status status code.
	141	* @param hVScsiLun Virtual SCSI LUN handle.
	142	* @param pvScsiLunUser Opaque user data which may
	143	* be used to identify the medium.
	144	* @param fLocked New lock state (locked/unlocked).
	145	*/
	146	DECLR3CALLBACKMEMBER(int, pfnVScsiLunMediumSetLock, (VSCSILUN hVScsiLun,
	147	void *pvScsiLunUser,
	148	bool fLocked));
	149	/**
[27653]	150	* Enqueue a read or write request from the medium.
	151	*
	152	* @returns VBox status status code.
	153	* @param hVScsiLun Virtual SCSI LUN handle.
	154	* @param pvScsiLunUser Opaque user data which may
	155	* be used to identify the medium.
	156	* @param hVScsiIoReq Virtual SCSI I/O request handle.
	157	*/
	158	DECLR3CALLBACKMEMBER(int, pfnVScsiLunReqTransferEnqueue, (VSCSILUN hVScsiLun,
	159	void *pvScsiLunUser,
	160	VSCSIIOREQ hVScsiIoReq));
	161
[38680]	162	/**
	163	* Returns flags of supported features.
	164	*
	165	* @returns VBox status status code.
	166	* @param hVScsiLun Virtual SCSI LUN handle.
	167	* @param pvScsiLunUser Opaque user data which may
	168	* be used to identify the medium.
	169	* @param hVScsiIoReq Virtual SCSI I/O request handle.
	170	*/
	171	DECLR3CALLBACKMEMBER(int, pfnVScsiLunGetFeatureFlags, (VSCSILUN hVScsiLun,
	172	void *pvScsiLunUser,
	173	uint64_t *pfFeatures));
	174
	175
[27653]	176	} VSCSILUNIOCALLBACKS;
	177	/** Pointer to a virtual SCSI LUN I/O callback table. */
	178	typedef VSCSILUNIOCALLBACKS *PVSCSILUNIOCALLBACKS;
	179
	180	/**
	181	* The virtual SCSI request completed callback.
	182	*/
	183	typedef DECLCALLBACK(void) FNVSCSIREQCOMPLETED(VSCSIDEVICE hVScsiDevice,
	184	void *pvVScsiDeviceUser,
	185	void *pvVScsiReqUser,
[32983]	186	int rcScsiCode,
	187	bool fRedoPossible,
[27653]	188	int rcReq);
	189	/** Pointer to a virtual SCSI request completed callback. */
	190	typedef FNVSCSIREQCOMPLETED *PFNVSCSIREQCOMPLETED;
	191
	192	/**
	193	* Create a new empty SCSI device instance.
	194	*
	195	* @returns VBox status code.
	196	* @param phVScsiDevice Where to store the SCSI device handle.
	197	* @param pfnVScsiReqCompleted The method call after a request completed.
	198	* @param pvVScsiDeviceUser Opaque user data given in the completion callback.
	199	*/
	200	VBOXDDU_DECL(int) VSCSIDeviceCreate(PVSCSIDEVICE phVScsiDevice,
	201	PFNVSCSIREQCOMPLETED pfnVScsiReqCompleted,
	202	void *pvVScsiDeviceUser);
	203
	204	/**
	205	* Destroy a SCSI device instance.
	206	*
	207	* @returns VBox status code.
	208	* @param hScsiDevice The SCSI device handle to destroy.
	209	*/
	210	VBOXDDU_DECL(int) VSCSIDeviceDestroy(VSCSIDEVICE hVScsiDevice);
	211
	212	/**
	213	* Attach a LUN to the SCSI device.
	214	*
	215	* @returns VBox status code.
	216	* @param hScsiDevice The SCSI device handle to add the LUN to.
	217	* @param hScsiLun The LUN handle to add.
	218	* @param iLun The LUN number.
	219	*/
	220	VBOXDDU_DECL(int) VSCSIDeviceLunAttach(VSCSIDEVICE hVScsiDevice, VSCSILUN hVScsiLun, uint32_t iLun);
	221
	222	/**
	223	* Detach a LUN from the SCSI device.
	224	*
	225	* @returns VBox status code.
	226	* @param hVScsiDevice The SCSI device handle to add the LUN to.
	227	* @param iLun The LUN number to remove.
	228	* @param phVScsiLun Where to store the detached LUN handle.
	229	*/
	230	VBOXDDU_DECL(int) VSCSIDeviceLunDetach(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
	231	PVSCSILUN phVScsiLun);
	232
	233	/**
	234	* Return the SCSI LUN handle.
	235	*
	236	* @returns VBox status code.
	237	* @param hVScsiDevice The SCSI device handle.
	238	* @param iLun The LUN number to get.
	239	* @param phVScsiLun Where to store the LUN handle.
	240	*/
	241	VBOXDDU_DECL(int) VSCSIDeviceLunGet(VSCSIDEVICE hVScsiDevice, uint32_t iLun,
	242	PVSCSILUN phVScsiLun);
	243
	244	/**
	245	* Enqueue a request to the SCSI device.
	246	*
	247	* @returns VBox status code.
	248	* @param hVScsiDevice The SCSI device handle.
	249	* @param hVScsiReq The SCSI request handle to enqueue.
	250	*/
	251	VBOXDDU_DECL(int) VSCSIDeviceReqEnqueue(VSCSIDEVICE hVScsiDevice, VSCSIREQ hVScsiReq);
	252
	253	/**
	254	* Allocate a new request handle.
	255	*
	256	* @returns VBox status code.
	257	* @param phVScsiDevice The SCSI device handle.
	258	* @param phVScsiReq Where to SCSI request handle.
	259	* @param iLun The LUN the request is for.
	260	* @param pbCDB The CDB for the request.
	261	* @param cbCDB The size of the CDB in bytes.
	262	* @param cbSGList Number of bytes the S/G list describes.
	263	* @param cSGListEntries Number of S/G list entries.
	264	* @param paSGList Pointer to the S/G list.
	265	* @param pbSense Pointer to the sense buffer.
	266	* @param cbSense Size of the sense buffer.
	267	* @param pvVScsiReqUser Opqaue user data returned when the request completes.
	268	*/
	269	VBOXDDU_DECL(int) VSCSIDeviceReqCreate(VSCSIDEVICE hVScsiDevice, PVSCSIREQ phVScsiReq,
	270	uint32_t iLun, uint8_t *pbCDB, size_t cbCDB,
	271	size_t cbSGList, unsigned cSGListEntries,
[28065]	272	PCRTSGSEG paSGList, uint8_t *pbSense,
[27653]	273	size_t cbSense, void *pvVScsiReqUser);
	274
	275	/**
	276	* Create a new LUN.
	277	*
	278	* @returns VBox status code.
	279	* @param phVScsiLun Where to store the SCSI LUN handle.
	280	* @param enmLunType The Lun type.
	281	* @param pVScsiLunIoCallbacks Pointer to the I/O callbacks to use for his LUN.
	282	* @param pvVScsiLunUser Opaque user argument which
	283	* is returned in the pvScsiLunUser parameter
	284	* when the request completion callback is called.
	285	*/
	286	VBOXDDU_DECL(int) VSCSILunCreate(PVSCSILUN phVScsiLun, VSCSILUNTYPE enmLunType,
	287	PVSCSILUNIOCALLBACKS pVScsiLunIoCallbacks,
	288	void *pvVScsiLunUser);
	289
	290	/**
	291	* Destroy virtual SCSI LUN.
	292	*
	293	* @returns VBox status code.
[33540]	294	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
[27653]	295	*/
	296	VBOXDDU_DECL(int) VSCSILunDestroy(VSCSILUN hVScsiLun);
	297
	298	/**
[43640]	299	* Notify virtual SCSI LUN of medium being mounted.
	300	*
	301	* @returns VBox status code.
	302	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
	303	*/
	304	VBOXDDU_DECL(int) VSCSILunMountNotify(VSCSILUN hVScsiLun);
	305
	306	/**
	307	* Notify virtual SCSI LUN of medium being unmounted.
	308	*
	309	* @returns VBox status code.
	310	* @param hVScsiLun The virtual SCSI LUN handle to destroy.
	311	*/
	312	VBOXDDU_DECL(int) VSCSILunUnmountNotify(VSCSILUN hVScsiLun);
	313
	314	/**
[27653]	315	* Notify a that a I/O request completed.
	316	*
	317	* @returns VBox status code.
	318	* @param hVScsiIoReq The I/O request handle that completed.
	319	* This is given when a I/O callback for
	320	* the LUN is called by the virtual SCSI layer.
	321	* @param rcIoReq The status code the I/O request completed with.
[32983]	322	* @param fRedoPossible Flag whether it is possible to redo the request.
	323	* If true setting any sense code will be omitted
	324	* in case of an error to not alter the device state.
[27653]	325	*/
[32983]	326	VBOXDDU_DECL(int) VSCSIIoReqCompleted(VSCSIIOREQ hVScsiIoReq, int rcIoReq, bool fRedoPossible);
[27653]	327
	328	/**
	329	* Query the transfer direction of the I/O request.
	330	*
	331	* @returns Transfer direction.of the given I/O request
	332	* @param hVScsiIoReq The SCSI I/O request handle.
	333	*/
	334	VBOXDDU_DECL(VSCSIIOREQTXDIR) VSCSIIoReqTxDirGet(VSCSIIOREQ hVScsiIoReq);
	335
	336	/**
	337	* Query I/O parameters.
	338	*
	339	* @returns VBox status code.
	340	* @param hVScsiIoReq The SCSI I/O request handle.
	341	* @param puOffset Where to store the start offset.
	342	* @param pcbTransfer Where to store the amount of bytes to transfer.
	343	* @param pcSeg Where to store the number of segments in the S/G list.
	344	* @param pcbSeg Where to store the number of bytes the S/G list describes.
	345	* @param ppaSeg Where to store the pointer to the S/G list.
	346	*/
	347	VBOXDDU_DECL(int) VSCSIIoReqParamsGet(VSCSIIOREQ hVScsiIoReq, uint64_t *puOffset,
	348	size_t pcbTransfer, unsigned pcSeg,
[28065]	349	size_t pcbSeg, PCRTSGSEG ppaSeg);
[27653]	350
[38680]	351	/**
	352	* Query unmap parameters.
	353	*
	354	* @returns VBox status code.
	355	* @param hVScsiIoReq The SCSI I/O request handle.
	356	* @param ppaRanges Where to store the pointer to the range array on success.
	357	* @param pcRanges Where to store the number of ranges on success.
	358	*/
[38878]	359	VBOXDDU_DECL(int) VSCSIIoReqUnmapParamsGet(VSCSIIOREQ hVScsiIoReq, PCRTRANGE *ppaRanges,
[38680]	360	unsigned *pcRanges);
	361
[27653]	362	RT_C_DECLS_END
	363
	364	#endif /* ___VBox_vscsi_h */
	365

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

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

Download in other formats: