1/*
2 * Copyright (c) 1998-2012 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24
25#ifndef _IOKIT_IOUSBMASSSTORAGEUFISUBCLASS_H
26#define _IOKIT_IOUSBMASSSTORAGEUFISUBCLASS_H
27
28// This class' header file
29#include <IOKit/usb/IOUSBMassStorageClass.h>
30#include <IOKit/scsi/IOSCSIPrimaryCommandsDevice.h>
31
32
33#pragma mark -
34#pragma mark IOUSBMassStorageUFIDevice declaration
35
36class IOUSBMassStorageUFIDevice : public IOSCSIPrimaryCommandsDevice
37{
38    OSDeclareDefaultStructors(IOUSBMassStorageUFIDevice)
39
40private:
41	static void			AsyncReadWriteComplete( SCSITaskIdentifier	completedTask );
42
43protected:
44    // Reserve space for future expansion.
45    struct IOUSBMassStorageUFIDeviceExpansionData
46	{
47	};
48    IOUSBMassStorageUFIDeviceExpansionData *fIOUSBMassStorageUFIDeviceReserved;
49
50	// ---- Medium Characteristics ----
51	bool				fMediumPresent;
52
53	// The byte count of each physical block on the medium.
54	UInt32				fMediumBlockSize;
55
56	// The total number of blocks of fMediumBlockSize on the medium.
57	UInt32				fMediumBlockCount;
58
59	// Whether the installed medium is protected from writes
60	bool				fMediumIsWriteProtected;
61
62	// Polling thread variables
63	thread_call_t		fPollingThread;
64	UInt32				fPollingMode;
65	enum
66	{
67		kPollingMode_Suspended		= 0,
68		kPollingMode_NewMedia 		= 1,
69		kPollingMode_MediaRemoval	= 2
70	};
71
72	// ---- Methods for controlling the current state of device support ----
73	virtual bool		InitializeDeviceSupport( void );
74	virtual void 		StartDeviceSupport ( void );
75	virtual void		SuspendDeviceSupport( void );
76	virtual void		ResumeDeviceSupport( void );
77	virtual void 		StopDeviceSupport ( void );
78	virtual void		TerminateDeviceSupport( void );
79
80	// ---- Methods used for misc  ----
81	virtual bool		ClearNotReadyStatus( void );
82	virtual void 		CreateStorageServiceNub( void );
83	virtual bool		DetermineDeviceCharacteristics( void );
84
85	// ---- Methods used for controlling the polling thread ----
86	virtual void		ProcessPoll( void );
87	virtual void		EnablePolling( void );
88	virtual void		DisablePolling( void );
89
90	// ---- Main and support methods for polling for new Media ----
91	virtual void		PollForNewMedia( void );
92	virtual bool		DetermineMediaPresence( void );
93	virtual bool		DetermineMediumCapacity(
94							UInt64 * 				blockSize,
95							UInt64 * 				blockCount );
96	virtual bool		DetermineMediumWriteProtectState( void );
97
98	// ---- Main and support methods for polling for Media removal ----
99	virtual void		PollForMediaRemoval( void );
100
101	// ---- Methods used for power managment ----
102	virtual UInt32		GetInitialPowerState ( void );
103	virtual void 		InitializePowerManagement ( IOService * provider );
104	virtual void		HandlePowerChange ( void );
105	virtual void		HandleCheckPowerState ( void );
106	virtual void		TicklePowerManager ( void );
107	virtual UInt32		GetNumberOfPowerStateTransitions ( void );
108
109	// ---- Methods used for handling medium characteristics ----
110    virtual void		SetMediumCharacteristics(
111    						UInt32 					blockSize,
112    						UInt32 					blockCount );
113
114	virtual void		ResetMediumCharacteristics( void );
115
116	virtual IOReturn	IssueRead(
117							IOMemoryDescriptor *	buffer,
118                         	UInt64					startBlock,
119                     		UInt64					blockCount );
120
121	virtual IOReturn	IssueRead(
122							IOMemoryDescriptor *	buffer,
123                      		UInt64					startBlock,
124                     		UInt64					blockCount,
125                       		void * 					clientData );
126
127
128	virtual IOReturn	IssueWrite(
129							IOMemoryDescriptor *	buffer,
130                    		UInt64					startBlock,
131                       		UInt64					blockCount );
132
133	virtual IOReturn	IssueWrite(
134							IOMemoryDescriptor *	buffer,
135                         	UInt64					startBlock,
136                      		UInt64					blockCount,
137							void * 					clientData );
138
139public:
140
141	static 	void		sProcessPoll( void * pdtDriver, void * refCon );
142
143	// Interface to the UFI Storage Services Driver
144	// ---- Methods for controlling the device ----
145	virtual IOReturn	SyncReadWrite(
146							IOMemoryDescriptor *	buffer,
147							UInt64					startBlock,
148							UInt64					blockCount,
149							UInt64					blockSize );
150
151	virtual IOReturn	AsyncReadWrite(
152							IOMemoryDescriptor *	buffer,
153							UInt64					startBlock,
154							UInt64					blockCount,
155							UInt64					blockSize,
156							void * 					clientData );
157
158	// ---- Methods for controlling medium state ----
159	virtual IOReturn	EjectTheMedium( void );
160
161	// ---- Methods for controlling media format ----
162	virtual IOReturn	FormatMedium(
163							UInt64 					blockCount,
164							UInt64 					blockSize );
165	virtual UInt32		GetFormatCapacities(
166							UInt64 * 				capacities,
167             				UInt32   				capacitiesMaxCount ) const;
168
169	// ---- Query methods to report device characteristics ----
170	// Report the maximum number of blocks that the device can handle per
171	// read or write.  A value of 0 (zero) indicates there is no limit aside
172	// from the size of the method's return parameter.
173	virtual UInt64		ReportDeviceMaxBlocksReadTransfer( void );
174	virtual UInt64		ReportDeviceMaxBlocksWriteTransfer( void );
175
176	// ---- Query methods to report installed medium characteristics ----
177	virtual UInt64		ReportMediumBlockSize( void );
178	virtual UInt64		ReportMediumTotalBlockCount( void );
179	virtual bool		ReportMediumWriteProtection( void );
180
181	// Methods for getting device information strings
182	virtual char *		GetVendorString( void );
183	virtual char *		GetProductString( void );
184	virtual char *		GetRevisionString( void );
185	OSDictionary *		GetProtocolCharacteristicsDictionary ( void );
186	OSDictionary *		GetDeviceCharacteristicsDictionary ( void );
187
188protected:
189	// Utility methods used by all SCSI Command Set objects
190
191	// isParameterValid methods are used to validate that the parameter passed into
192	// the command methods are of the correct value.
193
194	// Validate Parameter used for 1 bit to 1 byte paramaters
195    bool		 	IsParameterValid(
196							SCSICmdField1Byte 			param,
197							SCSICmdField1Byte 			mask );
198
199	// Validate Parameter used for 9 bit to 2 byte paramaters
200	bool		 	IsParameterValid(
201							SCSICmdField2Byte 			param,
202							SCSICmdField2Byte 			mask );
203
204	// Validate Parameter used for 17 bit to 4 byte paramaters
205	bool		 	IsParameterValid(
206							SCSICmdField4Byte 			param,
207							SCSICmdField4Byte 			mask );
208
209	// UFI Required Commands
210	virtual bool 	FORMAT_UNIT(
211							SCSITaskIdentifier			request,
212			    			IOMemoryDescriptor *		dataBuffer,
213			    			IOByteCount					defectListSize,
214			    			SCSICmdField1Byte 			TRACK_NUMBER,
215			    			SCSICmdField2Byte 			INTERLEAVE );
216
217	virtual bool	INQUIRY(
218							SCSITaskIdentifier			request,
219    						IOMemoryDescriptor 			*dataBuffer,
220    						SCSICmdField1Byte 			PAGE_OR_OPERATION_CODE,
221    						SCSICmdField1Byte 			ALLOCATION_LENGTH );
222
223   	virtual bool	MODE_SELECT_10(
224							SCSITaskIdentifier			request,
225    						IOMemoryDescriptor 			*dataBuffer,
226    						SCSICmdField1Bit 			PF,
227    						SCSICmdField1Bit 			SP,
228    						SCSICmdField2Byte 			PARAMETER_LIST_LENGTH );
229
230   	virtual bool	MODE_SENSE_10(
231							SCSITaskIdentifier			request,
232    						IOMemoryDescriptor 			*dataBuffer,
233    						SCSICmdField1Bit 			DBD,
234	   						SCSICmdField2Bit 			PC,
235	   						SCSICmdField6Bit 			PAGE_CODE,
236	   						SCSICmdField2Byte 			PARAMETER_LIST_LENGTH );
237
238    virtual bool	PREVENT_ALLOW_MEDIUM_REMOVAL(
239							SCSITaskIdentifier			request,
240	     					SCSICmdField1Bit 			PREVENT );
241
242	virtual bool 	READ_10(
243							SCSITaskIdentifier			request,
244			    			IOMemoryDescriptor *		dataBuffer,
245			    			UInt32						blockSize,
246			    			SCSICmdField1Bit 			DPO,
247			    			SCSICmdField1Bit 			FUA,
248							SCSICmdField1Bit 			RELADR,
249							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
250							SCSICmdField2Byte 			TRANSFER_LENGTH );
251
252	virtual bool 	READ_12(
253							SCSITaskIdentifier			request,
254			    			IOMemoryDescriptor *		dataBuffer,
255			    			UInt32						blockSize,
256			    			SCSICmdField1Bit 			DPO,
257			    			SCSICmdField1Bit 			FUA,
258							SCSICmdField1Bit 			RELADR,
259							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
260							SCSICmdField4Byte 			TRANSFER_LENGTH );
261
262	virtual bool 	READ_CAPACITY(
263							SCSITaskIdentifier			request,
264			    			IOMemoryDescriptor *		dataBuffer,
265			    			SCSICmdField1Bit 			RELADR,
266							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
267							SCSICmdField1Bit 			PMI );
268
269	virtual bool 	READ_FORMAT_CAPACITIES(
270							SCSITaskIdentifier			request,
271			    			IOMemoryDescriptor *		dataBuffer,
272			    			SCSICmdField2Byte 			ALLOCATION_LENGTH );
273
274	virtual bool 	REQUEST_SENSE(
275							SCSITaskIdentifier			request,
276   							IOMemoryDescriptor 			*dataBuffer,
277			    			SCSICmdField1Byte 			ALLOCATION_LENGTH );
278
279	virtual bool 	REZERO_UNIT(
280							SCSITaskIdentifier			request );
281
282	virtual bool 	SEEK(
283							SCSITaskIdentifier			request,
284			    			SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS );
285
286	virtual bool 	SEND_DIAGNOSTICS(
287							SCSITaskIdentifier			request,
288							SCSICmdField1Bit 			PF,
289							SCSICmdField1Bit 			SELF_TEST,
290							SCSICmdField1Bit 			DEF_OFL,
291							SCSICmdField1Bit 			UNIT_OFL );
292
293	virtual bool 	START_STOP_UNIT(
294							SCSITaskIdentifier			request,
295							SCSICmdField1Bit 			IMMED,
296							SCSICmdField1Bit 			LOEJ,
297							SCSICmdField1Bit 			START );
298
299    virtual bool 	TEST_UNIT_READY(
300							SCSITaskIdentifier			request );
301
302	virtual bool 	VERIFY(
303							SCSITaskIdentifier			request,
304							SCSICmdField1Bit 			DPO,
305							SCSICmdField1Bit 			BYTCHK,
306							SCSICmdField1Bit 			RELADR,
307							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
308							SCSICmdField2Byte 			VERIFICATION_LENGTH );
309
310	virtual bool 	WRITE_10(
311							SCSITaskIdentifier			request,
312			    			IOMemoryDescriptor *		dataBuffer,
313			    			UInt32						blockSize,
314			    			SCSICmdField1Bit 			DPO,
315			    			SCSICmdField1Bit 			FUA,
316							SCSICmdField1Bit 			RELADR,
317							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
318							SCSICmdField2Byte 			TRANSFER_LENGTH );
319
320	virtual bool 	WRITE_12(
321							SCSITaskIdentifier			request,
322							IOMemoryDescriptor *		dataBuffer,
323			    			UInt32						blockSize,
324			    			SCSICmdField1Bit 			DPO,
325							SCSICmdField1Bit 			EBP,
326							SCSICmdField1Bit 			RELADR,
327							SCSICmdField4Byte 			LOGICAL_BLOCK_ADDRESS,
328							SCSICmdField4Byte 			TRANSFER_LENGTH );
329
330	virtual bool 	WRITE_AND_VERIFY(
331							SCSITaskIdentifier			request,
332			    			IOMemoryDescriptor *		dataBuffer,
333			    			UInt32						blockSize,
334			    			SCSICmdField1Bit 			DPO,
335			    			SCSICmdField1Bit 			BYTCHK,
336			    			SCSICmdField1Bit 			RELADR,
337			    			SCSICmdField4Byte			LOGICAL_BLOCK_ADDRESS,
338			    			SCSICmdField2Byte 			TRANSFER_LENGTH );
339};
340
341
342#pragma mark -
343#pragma mark IOUSBMassStorageUFISubclass declaration
344
345
346class IOUSBMassStorageUFISubclass : public IOUSBMassStorageClass
347{
348    OSDeclareDefaultStructors(IOUSBMassStorageUFISubclass)
349
350protected:
351	virtual	bool		BeginProvidedServices( void );
352	virtual	bool		EndProvidedServices( void );
353};
354
355#endif //_IOKIT_IOUSBMASSSTORAGEUFISUBCLASS_H
356