1/*
2 * Copyright (c) 1998-2009 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/*!
26  @header IOFireWireSerialBusProtocolTransport
27  Contains the class definition for IOFireWireSerialBusProtocolTransport.
28*/
29
30
31#ifndef _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_
32#define _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_
33
34
35#include <IOKit/IOBufferMemoryDescriptor.h>
36#include <IOKit/IOLib.h>
37#include <IOKit/IOMessage.h>
38#include <IOKit/IOService.h>
39#include <IOKit/IOCommandPool.h>
40#include <IOKit/firewire/IOFireWireUnit.h>
41#include <IOKit/sbp2/IOFireWireSBP2LUN.h>
42
43#include <IOKit/scsi/IOSCSIProtocolServices.h>
44
45/*!
46	@class IOFireWireSerialBusProtocolTransport
47	@abstract SCSI Protocol Driver Family for FireWire SBP2 Devices.
48	@discussion IOFireWireSerialBusProtocolTransport contains all the bus specific support for FireWire
49	SBP2 compliant devices. To add vendor specific features or workarounds you will sub-class the appropriate
50	methods of this family.
51*/
52
53class IOFireWireSerialBusProtocolTransport : public IOSCSIProtocolServices
54{
55
56	OSDeclareDefaultStructors ( IOFireWireSerialBusProtocolTransport )
57
58private:
59
60	IOFireWireUnit *				fUnit;
61	IOFireWireSBP2LUN *				fSBPTarget;
62	IOFireWireSBP2Login *			fLogin;
63	IOFireWireSBP2ORB *				fORB;
64	IOFireWireSBP2ManagementORB * 	fLUNResetORB;
65
66	// /!\ WARNING! NOT USED left behind for legacy binary reasons
67	IOSimpleLock *					fQueueLock;
68
69	UInt32							fLoginRetryCount;
70	bool							fDeferRegisterService;
71	bool							fNeedLogin;
72
73    // /!\ WARNING! NOT USED left behind for legacy binary reasons
74	bool							fPhysicallyConnected;
75
76	static void
77	StatusNotifyStatic ( void * refCon, FWSBP2NotifyParamsPtr params );
78
79	static void
80	UnsolicitedStatusNotifyStatic (	void * 					refCon,
81									FWSBP2NotifyParamsPtr 	params );
82
83	static void
84	LunResetCompleteStatic (	void * 							refCon,
85								IOReturn						status,
86								IOFireWireSBP2ManagementORB * 	orb );
87
88	static void
89	FetchAgentResetCompleteStatic (	void * refcon,
90									IOReturn status );
91
92	static IOReturn
93	ConnectToDeviceStatic (	OSObject * refCon, void *, void *, void *, void * );
94
95	virtual void
96	FetchAgentResetComplete ( IOReturn status );
97
98	static void LoginCompletionStatic ( void * refCon, FWSBP2LoginCompleteParams * params );
99
100	static void
101	LogoutCompletionStatic ( void * refCon, FWSBP2LogoutCompleteParams * params );
102
103	/*!
104		@function CoalesceSenseData
105		@abstract CoalesceSenseData convert a SBP-2 status block into a SPC-2 sense block.
106		@discussion	CoalesceSenseData pulls the appropriate bits out of the SBP2 sense block
107		as defined in SBP-2 Annex B section B.2 and dynamically builds a sense data block as
108		defined in SPC-2 section 7.23.2.
109	*/
110
111	SCSITaskStatus
112	CoalesceSenseData (	FWSBP2StatusBlock *	sourceData,
113						UInt8				quadletCount,
114						SCSI_Sense_Data *	targetData );
115
116	virtual void ConnectToDevice ( void );
117
118	virtual void DisconnectFromDevice ( void );
119
120	virtual bool IsDeviceCPUInDiskMode ( void );
121
122protected:
123
124	/*!
125		@function AllocateResources
126		@abstract Allocate Resources.
127		@discussion	Called from start method to allocate needed resources.
128	*/
129
130	virtual IOReturn AllocateResources ( void );
131
132	/*!
133		@function DeallocateResources
134		@abstract Deallocate Resources.
135		@discussion	Called from cleanUp method to deallocate resources.
136	*/
137
138	virtual void DeallocateResources ( void );
139
140	enum SBP2LoginState
141	{
142		kFirstTimeLoggingInState,
143		kLogginSucceededState,
144		kLogginFailedState
145	};
146
147	/*!
148		@typedef SBP2ClientOrbData
149		@param orb IOFireWireSBP2ORB for request.
150		@param scsiTask SCSITaskIdentifier of request.
151		@param serviceResponse SCSIServiceResponse of request.
152		@param taskStatus SCSITaskStatus of request.
153		@discussion This structure is stuffed into the refcon so we can associate which
154		IOFireWireSBP2ORB and SCSITaskIdentifier is completing.
155	*/
156
157	typedef struct {
158		IOFireWireSBP2ORB *				orb;
159		SCSITaskIdentifier 				scsiTask;
160		SCSIServiceResponse 			serviceResponse;
161		SCSITaskStatus					taskStatus;
162		IOBufferMemoryDescriptor *		quadletAlignedBuffer;
163	} SBP2ClientOrbData;
164
165	static const UInt32 kDefaultBusyTimeoutValue	= 0x0000000F;
166	static const UInt64 kMaxFireWireLUN				= 0xFFFF;
167	static const UInt32 kMaxFireWirePayload			= 4096;
168	static const UInt32 kMaxLoginRetryCount			= 8;
169	static const UInt32 kMaxReconnectCount			= 128;
170	static const UInt32 kCSRModelInfoKey			= 0x17;
171
172	UInt32	fReconnectCount;
173	bool 	fLoggedIn;
174
175	// binary compatibility instance variable expansion
176	struct ExpansionData
177	{
178		IOCommandPool *		fCommandPool;
179		IOCommandPool *		fSubmitQueue;
180		SBP2LoginState		fLoginState;
181		bool				fLUNResetPathFlag;
182		int					fLUNResetCount;
183		bool				fAlwaysSetSenseData;
184		bool				fAutonomousSpinDownWorkAround;
185	};
186
187	ExpansionData * reserved;
188
189	bool fObjectIsOpen;
190
191	/*!
192		@function CommandORBAccessor
193		@abstract accessor function for fORB.
194		@discussion	xxx.
195	*/
196
197	IOFireWireSBP2ORB * CommandORBAccessor ( void );
198
199	/*!
200		@function SBP2LoginAccessor
201		@abstract accessor function for fLogin.
202		@discussion	xxx.
203	*/
204
205	IOFireWireSBP2Login * SBP2LoginAccessor ( void );
206
207	virtual IOReturn
208	message ( UInt32 type, IOService * provider, void * argument = 0 );
209
210	/*!
211		@function SendSCSICommand
212		@abstract Prepare and send a SCSI command to the device.
213		@discussion	The incoming SCSITaskIdentifier gets turned into a IOFireWireSBP2ORB
214		and is submitted to the SBP2 layer. See IOSCSIProtocolServices.h for more details
215		regarding SendSCSICommand. Also see IOFireWireSBP2Lib.h for details regarding the
216		IOFireWireSBP2ORB structure and the submitORB method.
217		@result If the command was sent to the device and is pending completion, the
218		subclass should return true and return back the kSCSIServiceResponse_Request_In_Process response.
219		If the command completes immediately with an error, the subclass will return true
220		and return back the appropriate status. If the subclass is currently processing all the
221		commands it can, the subclass will return false and the command will be resent next time
222		CommandCompleted is called.
223	*/
224
225	virtual bool
226	SendSCSICommand (	SCSITaskIdentifier 		request,
227						SCSIServiceResponse *	serviceResponse,
228						SCSITaskStatus *		taskStatus );
229
230	/*!
231		@function SetCommandBuffers
232		@abstract Method to set orb's buffers.
233		@discussion	This method was added so that subclasses can override and massage buffers as
234		needed. The default simply calls setCommandBuffers. See IOFireWireSBP2Lib.h for details
235		regarding the setCommandBuffers method.
236		@result xxx.
237	*/
238
239	virtual IOReturn
240	SetCommandBuffers (	IOFireWireSBP2ORB * orb, SCSITaskIdentifier request );
241
242	/*!
243		@function CompleteSCSITask
244		@abstract This qualifies and sets appropriate data then calls CommandCompleted.
245		@discussion	See IOSCSIProtocolServices.h for more details
246		regarding CommandCompleted.
247	*/
248
249	virtual void
250	CompleteSCSITask ( IOFireWireSBP2ORB * orb );
251
252	/*!
253		@function AbortSCSICommand
254		@abstract This method is intended to abort an in progress SCSI Task.
255		@discussion	Currently not implemented in super class. This is a stub method for adding
256		the abort command in the near future.
257		@result See SCSITask.h for SCSIServiceResponse codes.
258	*/
259
260	virtual SCSIServiceResponse
261	AbortSCSICommand ( SCSITaskIdentifier request );
262
263	/*!
264		@function StatusNotify
265		@abstract This is our handler for status.
266		@discussion See IOFireWireSBP2Lib.h for details regarding the FWSBP2NotifyParams
267		structure that is passed in to the completion..
268	*/
269
270	virtual void
271	StatusNotify ( FWSBP2NotifyParams * params );
272
273	/*!
274		@function SetValidAutoSenseData
275		@abstract Set the auto sense data that was returned for a given SCSI Task.
276		@discussion	SetValidAutoSenseData is called to qualify sense data that is copied to the
277		client via the SetAutoSenseData method. See IOSCSIProtocolServices.h for more details
278		regarding SetAutoSenseData.
279	*/
280
281	void
282	SetValidAutoSenseData (	SBP2ClientOrbData *	clientData,
283							FWSBP2StatusBlock *	statusBlock,
284							SCSI_Sense_Data *	targetData );
285
286	/*!
287		@function UnsolicitedStatusNotify
288		@abstract This is our handler for unsolicited status.
289		@discussion	After we have parsed and handled the unsolicited status we call
290		enableUnsolicitedStatus. See IOFireWireSBP2Lib.h for details regarding the
291		enableUnsolicitedStatus method.
292	*/
293
294	virtual void
295	UnsolicitedStatusNotify ( FWSBP2NotifyParamsPtr params );
296
297	/*!
298		@function LoginCompletion
299		@abstract Completion routine for login complete.
300		@discussion	See IOFireWireSBP2Lib.h for details regarding the FWSBP2LogoutCompleteParams
301		structure that is passed in to the completion.
302	*/
303
304	virtual void
305	LoginCompletion ( FWSBP2LoginCompleteParams * params );
306
307	/*!
308		@function LogoutCompletion
309		@abstract Completion routine for logout complete.
310		@discussion	See IOFireWireSBP2Lib.h for details regarding the FWSBP2LogoutCompleteParams
311		structure that is passed in to the completion.
312	*/
313
314	virtual void
315	LogoutCompletion ( FWSBP2LogoutCompleteParams * params );
316
317	/*!
318		@function IsProtocolServiceSupported
319		@abstract Determine is specified feature is supported by the protocol layer.
320		@discussion	If the service has a value that must be returned, it will be returned in the
321		serviceValue output parameter. See IOSCSIProtocolServices.h for more details regarding
322		IsProtocolServiceSupported.
323		@result Will return true if the specified feature is supported by the protocol layer.
324	*/
325
326	virtual bool
327	IsProtocolServiceSupported ( SCSIProtocolFeature feature, void * serviceValue );
328
329	/*!
330		@function HandleProtocolServiceFeature
331		@abstract Handle specified feature supported by the protocol layer.
332		@discussion	See IOSCSIProtocolServices.h for more details regarding HandleProtocolServiceFeature.
333		@result Will return true if the specified feature is supported by the protocol layer.
334	*/
335
336	virtual bool
337	HandleProtocolServiceFeature ( SCSIProtocolFeature feature, void * serviceValue );
338
339	/*!
340		@function LunResetComplete
341		@abstract Callback to submit Fetch Agent Reset.
342		@discussion	See IOFireWireSBP2Lib.h for details regarding the submitFetchAgentReset
343		method.
344	*/
345
346	virtual void
347	LunResetComplete ( IOReturn status, IOFireWireSBP2ManagementORB * orb );
348
349public:
350
351	/*!
352		@function init
353		@abstract See IOService for discussion.
354		@discussion	Setup and prime class into known state.
355	*/
356
357	bool init ( OSDictionary * propTable );
358
359	/*!
360		@function start
361		@discussion See IOService for discussion.
362		@result Return true if the start was successful, false otherwise ( which will
363		cause the instance to be detached and usually freed ).
364	*/
365
366	virtual bool start ( IOService * provider );
367
368	/*!
369	 	@function cleanUp
370		@abstract cleanUp is called to tear down IOFireWireSerialBusProtocolTransport.
371		@discussion	cleanUp is called when we receive a kIOFWMessageServiceIsRequestingClose
372		message or if we fail our initialization.
373	*/
374
375	virtual void cleanUp ( void );
376
377	/*!
378		@function finalize
379		@abstract See IOService for discussion.
380		@result Returns true.
381	*/
382
383	virtual bool finalize ( IOOptionBits options );
384
385	/*!
386		@function free
387		@discussion See IOService for discussion.
388		@result none.
389	*/
390
391	virtual void free ( void );
392
393protected:
394
395	virtual IOReturn login ( void );
396    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 1 );
397
398	virtual IOReturn submitLogin ( void );
399    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 2 );
400
401	virtual void loginLost ( void );
402    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 3 );
403
404    void loginSuspended ( void );
405	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 4 );
406
407	virtual void loginResumed ( void );
408	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 5 );
409
410	static IOReturn CriticalOrbSubmissionStatic (
411			OSObject * refCon,
412			void * val1,
413			void * val2,
414			void * val3,
415			void * val4 );
416
417	/*!
418		@function CriticalOrbSubmission
419		@abstract xxx.
420		@discussion	xxx.
421		@result none.
422	*/
423
424	void
425		CriticalOrbSubmission (
426			IOFireWireSBP2ORB * orb,
427			SCSITaskIdentifier request );
428
429	virtual void submitOrbFromQueue ( void );
430	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 6 );
431
432private:
433
434	// binary compatibility reserved method space
435
436	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 7 );
437	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 8 );
438	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 9 );
439	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 10 );
440	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 11 );
441	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 12 );
442	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 13 );
443	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 14 );
444	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 15 );
445	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 16 );
446
447};
448
449#endif	/* _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_ */