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_ */