/*
 * Copyright (c) 1998-2009 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */


/*!
  @header IOFireWireSerialBusProtocolTransport
  Contains the class definition for IOFireWireSerialBusProtocolTransport.
*/


#ifndef _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_
#define _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_


#include <IOKit/IOBufferMemoryDescriptor.h>
#include <IOKit/IOLib.h>
#include <IOKit/IOMessage.h>
#include <IOKit/IOService.h>
#include <IOKit/IOCommandPool.h>
#include <IOKit/firewire/IOFireWireUnit.h>
#include <IOKit/sbp2/IOFireWireSBP2LUN.h>

#include <IOKit/scsi/IOSCSIProtocolServices.h>

/*!
	@class IOFireWireSerialBusProtocolTransport
	@abstract SCSI Protocol Driver Family for FireWire SBP2 Devices. 
	@discussion IOFireWireSerialBusProtocolTransport contains all the bus specific support for FireWire
	SBP2 compliant devices. To add vendor specific features or workarounds you will sub-class the appropriate
	methods of this family. 
*/

class IOFireWireSerialBusProtocolTransport : public IOSCSIProtocolServices
{
	
	OSDeclareDefaultStructors ( IOFireWireSerialBusProtocolTransport )
	
private:
	
	IOFireWireUnit *				fUnit;
	IOFireWireSBP2LUN *				fSBPTarget;
	IOFireWireSBP2Login *			fLogin;
	IOFireWireSBP2ORB *				fORB;
	IOFireWireSBP2ManagementORB * 	fLUNResetORB;
	
	// /!\ WARNING! NOT USED left behind for legacy binary reasons
	IOSimpleLock *					fQueueLock;
	
	UInt32							fLoginRetryCount;
	bool							fDeferRegisterService;
	bool							fNeedLogin;
    
    // /!\ WARNING! NOT USED left behind for legacy binary reasons
	bool							fPhysicallyConnected;
	
	static void
	StatusNotifyStatic ( void * refCon, FWSBP2NotifyParamsPtr params );
	
	static void
	UnsolicitedStatusNotifyStatic (	void * 					refCon,
									FWSBP2NotifyParamsPtr 	params );
	
	static void
	LunResetCompleteStatic (	void * 							refCon,
								IOReturn						status,
								IOFireWireSBP2ManagementORB * 	orb );
	
	static void
	FetchAgentResetCompleteStatic (	void * refcon,
									IOReturn status );
	
	static IOReturn
	ConnectToDeviceStatic (	OSObject * refCon, void *, void *, void *, void * );
	
	virtual void
	FetchAgentResetComplete ( IOReturn status );
	
	static void LoginCompletionStatic ( void * refCon, FWSBP2LoginCompleteParams * params );
	
	static void
	LogoutCompletionStatic ( void * refCon, FWSBP2LogoutCompleteParams * params );
	
	/*!
		@function CoalesceSenseData
		@abstract CoalesceSenseData convert a SBP-2 status block into a SPC-2 sense block.
		@discussion	CoalesceSenseData pulls the appropriate bits out of the SBP2 sense block
		as defined in SBP-2 Annex B section B.2 and dynamically builds a sense data block as
		defined in SPC-2 section 7.23.2.
	*/
	
	SCSITaskStatus
	CoalesceSenseData (	FWSBP2StatusBlock *	sourceData,
						UInt8				quadletCount,
						SCSI_Sense_Data *	targetData );
	
	virtual void ConnectToDevice ( void );
	
	virtual void DisconnectFromDevice ( void );
	
	virtual bool IsDeviceCPUInDiskMode ( void );

protected:
    
	/*!
		@function AllocateResources
		@abstract Allocate Resources.
		@discussion	Called from start method to allocate needed resources.
	*/
    
	virtual IOReturn AllocateResources ( void );
    
	/*!
		@function DeallocateResources
		@abstract Deallocate Resources.
		@discussion	Called from cleanUp method to deallocate resources.
	*/
    
	virtual void DeallocateResources ( void );
	
	enum SBP2LoginState
	{
		kFirstTimeLoggingInState,
		kLogginSucceededState,
		kLogginFailedState
	};
	
	/*! 
		@typedef SBP2ClientOrbData
		@param orb IOFireWireSBP2ORB for request.
		@param scsiTask SCSITaskIdentifier of request. 
		@param serviceResponse SCSIServiceResponse of request.
		@param taskStatus SCSITaskStatus of request.
		@discussion This structure is stuffed into the refcon so we can associate which
		IOFireWireSBP2ORB and SCSITaskIdentifier is completing.
	*/
	
	typedef struct {
		IOFireWireSBP2ORB *				orb;
		SCSITaskIdentifier 				scsiTask;
		SCSIServiceResponse 			serviceResponse;
		SCSITaskStatus					taskStatus;
		IOBufferMemoryDescriptor *		quadletAlignedBuffer;
	} SBP2ClientOrbData;
	
	static const UInt32 kDefaultBusyTimeoutValue	= 0x0000000F;
	static const UInt64 kMaxFireWireLUN				= 0xFFFF;
	static const UInt32 kMaxFireWirePayload			= 4096;
	static const UInt32 kMaxLoginRetryCount			= 8;
	static const UInt32 kMaxReconnectCount			= 128;
	static const UInt32 kCSRModelInfoKey			= 0x17;

	UInt32	fReconnectCount;
	bool 	fLoggedIn;
	
	// binary compatibility instance variable expansion
	struct ExpansionData
	{ 
		IOCommandPool *		fCommandPool;
		IOCommandPool *		fSubmitQueue;
		SBP2LoginState		fLoginState;
		bool				fLUNResetPathFlag;
		int					fLUNResetCount;
		bool				fAlwaysSetSenseData;
		bool				fAutonomousSpinDownWorkAround;
	};
	
	ExpansionData * reserved;
	
	bool fObjectIsOpen;

	/*!
		@function CommandORBAccessor
		@abstract accessor function for fORB.
		@discussion	xxx.
	*/

	IOFireWireSBP2ORB * CommandORBAccessor ( void );
   
	/*!
		@function SBP2LoginAccessor
		@abstract accessor function for fLogin.
		@discussion	xxx.
	*/

	IOFireWireSBP2Login * SBP2LoginAccessor ( void );

	virtual IOReturn
	message ( UInt32 type, IOService * provider, void * argument = 0 );

	/*!
		@function SendSCSICommand
		@abstract Prepare and send a SCSI command to the device.
		@discussion	The incoming SCSITaskIdentifier gets turned into a IOFireWireSBP2ORB
		and is submitted to the SBP2 layer. See IOSCSIProtocolServices.h for more details
		regarding SendSCSICommand. Also see IOFireWireSBP2Lib.h for details regarding the
		IOFireWireSBP2ORB structure and the submitORB method.
		@result If the command was sent to the device and is pending completion, the
		subclass should return true and return back the kSCSIServiceResponse_Request_In_Process response.
		If the command completes immediately with an error, the subclass will return true
		and return back the appropriate status. If the subclass is currently processing all the
		commands it can, the subclass will return false and the command will be resent next time
		CommandCompleted is called.
	*/

	virtual bool 
	SendSCSICommand (	SCSITaskIdentifier 		request,
						SCSIServiceResponse *	serviceResponse,
						SCSITaskStatus *		taskStatus );

	/*!
		@function SetCommandBuffers
		@abstract Method to set orb's buffers.
		@discussion	This method was added so that subclasses can override and massage buffers as
		needed. The default simply calls setCommandBuffers. See IOFireWireSBP2Lib.h for details
		regarding the setCommandBuffers method.
		@result xxx.
	*/
	
	virtual IOReturn
	SetCommandBuffers (	IOFireWireSBP2ORB * orb, SCSITaskIdentifier request );

	/*!
		@function CompleteSCSITask
		@abstract This qualifies and sets appropriate data then calls CommandCompleted.
		@discussion	See IOSCSIProtocolServices.h for more details
		regarding CommandCompleted.
	*/
	
	virtual void 
	CompleteSCSITask ( IOFireWireSBP2ORB * orb );

	/*!
		@function AbortSCSICommand
		@abstract This method is intended to abort an in progress SCSI Task.
		@discussion	Currently not implemented in super class. This is a stub method for adding
		the abort command in the near future.
		@result See SCSITask.h for SCSIServiceResponse codes.
	*/
	
	virtual SCSIServiceResponse 
	AbortSCSICommand ( SCSITaskIdentifier request );

	/*!
		@function StatusNotify
		@abstract This is our handler for status.
		@discussion See IOFireWireSBP2Lib.h for details regarding the FWSBP2NotifyParams
		structure that is passed in to the completion..
	*/
	
	virtual void
	StatusNotify ( FWSBP2NotifyParams * params );

	/*!
		@function SetValidAutoSenseData
		@abstract Set the auto sense data that was returned for a given SCSI Task.
		@discussion	SetValidAutoSenseData is called to qualify sense data that is copied to the
		client via the SetAutoSenseData method. See IOSCSIProtocolServices.h for more details
		regarding SetAutoSenseData.
	*/
	
	void
	SetValidAutoSenseData (	SBP2ClientOrbData *	clientData,
							FWSBP2StatusBlock *	statusBlock,
							SCSI_Sense_Data *	targetData );
	
	/*!
		@function UnsolicitedStatusNotify
		@abstract This is our handler for unsolicited status.
		@discussion	After we have parsed and handled the unsolicited status we call 
		enableUnsolicitedStatus. See IOFireWireSBP2Lib.h for details regarding the
		enableUnsolicitedStatus method.
	*/
	
	virtual void
	UnsolicitedStatusNotify ( FWSBP2NotifyParamsPtr params );

	/*!
		@function LoginCompletion
		@abstract Completion routine for login complete.
		@discussion	See IOFireWireSBP2Lib.h for details regarding the FWSBP2LogoutCompleteParams
		structure that is passed in to the completion.
	*/
	
	virtual void 
	LoginCompletion ( FWSBP2LoginCompleteParams * params );

	/*!
		@function LogoutCompletion
		@abstract Completion routine for logout complete.
		@discussion	See IOFireWireSBP2Lib.h for details regarding the FWSBP2LogoutCompleteParams
		structure that is passed in to the completion.
	*/
	
	virtual void 
	LogoutCompletion ( FWSBP2LogoutCompleteParams * params );

	/*!
		@function IsProtocolServiceSupported
		@abstract Determine is specified feature is supported by the protocol layer.
		@discussion	If the service has a value that must be returned, it will be returned in the
		serviceValue output parameter. See IOSCSIProtocolServices.h for more details regarding
		IsProtocolServiceSupported.
		@result Will return true if the specified feature is supported by the protocol layer.
	*/

	virtual bool
	IsProtocolServiceSupported ( SCSIProtocolFeature feature, void * serviceValue );

	/*!
		@function HandleProtocolServiceFeature
		@abstract Handle specified feature supported by the protocol layer.
		@discussion	See IOSCSIProtocolServices.h for more details regarding HandleProtocolServiceFeature.
		@result Will return true if the specified feature is supported by the protocol layer.
	*/

	virtual bool
	HandleProtocolServiceFeature ( SCSIProtocolFeature feature, void * serviceValue );
   
	/*!
		@function LunResetComplete
		@abstract Callback to submit Fetch Agent Reset.
		@discussion	See IOFireWireSBP2Lib.h for details regarding the submitFetchAgentReset
		method.
	*/
	
	virtual void
	LunResetComplete ( IOReturn status, IOFireWireSBP2ManagementORB * orb );

public:

	/*!
		@function init
		@abstract See IOService for discussion.
		@discussion	Setup and prime class into known state.
	*/
	
	bool init ( OSDictionary * propTable );

	/*! 
		@function start
		@discussion See IOService for discussion.
		@result Return true if the start was successful, false otherwise ( which will
		cause the instance to be detached and usually freed ).
	*/

	virtual bool start ( IOService * provider );
	
	/*!
	 	@function cleanUp
		@abstract cleanUp is called to tear down IOFireWireSerialBusProtocolTransport.
		@discussion	cleanUp is called when we receive a kIOFWMessageServiceIsRequestingClose
		message or if we fail our initialization.
	*/
	
	virtual void cleanUp ( void );
	
	/*!
		@function finalize
		@abstract See IOService for discussion.
		@result Returns true.
	*/
	
	virtual bool finalize ( IOOptionBits options );

	/*! 
		@function free
		@discussion See IOService for discussion.
		@result none.
	*/
	
	virtual void free ( void );
		
protected:
	
	virtual IOReturn login ( void );
    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 1 );
    
	virtual IOReturn submitLogin ( void );
    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 2 );
    
	virtual void loginLost ( void );
    OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 3 );
    
    void loginSuspended ( void );
	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 4 );
   
	virtual void loginResumed ( void );
	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 5 );

	static IOReturn CriticalOrbSubmissionStatic ( 
			OSObject * refCon, 
			void * val1,
			void * val2,
			void * val3,
			void * val4 );

	/*!
		@function CriticalOrbSubmission
		@abstract xxx.
		@discussion	xxx.
		@result none.
	*/
	
	void
		CriticalOrbSubmission (
			IOFireWireSBP2ORB * orb,
			SCSITaskIdentifier request );
	
	virtual void submitOrbFromQueue ( void );
	OSMetaClassDeclareReservedUsed ( IOFireWireSerialBusProtocolTransport, 6 );
	
private:
	
	// binary compatibility reserved method space
    
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 7 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 8 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 9 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 10 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 11 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 12 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 13 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 14 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 15 );
	OSMetaClassDeclareReservedUnused ( IOFireWireSerialBusProtocolTransport, 16 );
	
};

#endif	/* _IOKIT_IO_FIREWIRE_SERIAL_BUS_PROTOCOL_TRANSPORT_H_ */