sl@0: // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @file
sl@0:  @internalTechnology
sl@0:  @prototype
sl@0: */
sl@0: 
sl@0: #ifndef D32OTGDI_H
sl@0: #define D32OTGDI_H
sl@0: 
sl@0: #ifdef __KERNEL_MODE__
sl@0: #  include <kernel/klib.h>
sl@0: #  include <e32ver.h>
sl@0: #else
sl@0: #  include <e32base.h>
sl@0: #  include <e32ver.h>
sl@0: #  include <e32debug.h>
sl@0: #endif
sl@0: 
sl@0: #include <d32otgdi_errors.h>
sl@0: 
sl@0: /**
sl@0: The bi-directional interface which USB Manager uses to talk to OTGDI about 
sl@0: OTG related issues
sl@0: 
sl@0: @note This API is only available to USBMAN, a restriction which is enforced 
sl@0: by checking the SID of the calling process.
sl@0: */
sl@0: NONSHARABLE_CLASS(RUsbOtgDriver) : public RBusLogicalChannel
sl@0: 	{
sl@0: 	friend class DUsbOtgDriver;
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	// Version number history:
sl@0: 	//
sl@0: 	// PREQ1782 = 1.0
sl@0: 	// PREQ1305 = 1.1
sl@0: 	
sl@0: 	static const TInt KMajorVersionNumber = 1;
sl@0: 	static const TInt KMinorVersionNumber = 1;
sl@0: 
sl@0: private:
sl@0: 	
sl@0: 	/**
sl@0: 	OTG Event, supplied in a form that will enable use as an array
sl@0: 	index (note also how this is used below in the bit-mask form,
sl@0: 	but that this is only extended to a few, other events are OTG
sl@0: 	internal and used only to drive the local state machine)
sl@0: 	*/
sl@0: 	enum TOtgEventIndex
sl@0: 		{
sl@0: 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **
sl@0: 		'public' OTG events
sl@0: 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
sl@0: 
sl@0: 		/**
sl@0: 		OTG events related to plug insertion or removal
sl@0: 		*/
sl@0: 		EEventIndexAPlugInserted = 0,
sl@0: 		EEventIndexAPlugRemoved,
sl@0: 
sl@0: 		/**
sl@0: 		OTG events relating to changes visible on the bus
sl@0: 		*/
sl@0: 		EEventIndexVbusRaised,
sl@0: 		EEventIndexVbusDropped,
sl@0: 		
sl@0: 		EEventIndexSrpInitiated,
sl@0: 
sl@0: 		EEventIndexSrpReceived,
sl@0: 		EEventIndexHnpEnabled,
sl@0: 		EEventIndexHnpDisabled,
sl@0: 		EEventIndexHnpSupported,
sl@0: 		EEventIndexHnpAltSupported,
sl@0: 
sl@0: 		EEventIndexBusConnectionBusy,
sl@0: 		EEventIndexBusConnectionIdle,
sl@0: 		
sl@0: 		/**
sl@0: 		OTG events related to changes in the current role the device
sl@0: 		is performing (independant of the orientation of the connection)
sl@0: 		*/
sl@0: 		EEventIndexRoleChangedToHost,
sl@0: 		EEventIndexRoleChangedToDevice,
sl@0: 		EEventIndexRoleChangedToIdle,
sl@0: 
sl@0: 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **
sl@0: 		'private' OTG events - these are not converted to the bit-map form,
sl@0: 		but are used solely to stim the OTG state machine
sl@0: 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
sl@0: 		
sl@0: 		EEventIndexPrivateAfterThis,
sl@0: 
sl@0: 		EEventIndexVbusError,
sl@0: 		EEventIndexClearVbusError,
sl@0: 		
sl@0: 		EEventIndexResetStateMachine,
sl@0: 
sl@0: 		EEventIndexNoEvent,
sl@0: 
sl@0: 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **
sl@0: 		Single indicator used for array sizing
sl@0: 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
sl@0: 		EEventIndexNumEvents
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	OTG Events, supplied in a form that can be used to create a mask
sl@0: 	that can specify a watcher's events of interest.
sl@0: 	*/
sl@0: 	enum TOtgEvent
sl@0: 		{
sl@0: 		/**
sl@0: 		 * 'empty' dummy event
sl@0: 		 */
sl@0: 		EEventNotValid = 0,
sl@0: 		
sl@0: 		/**
sl@0: 		OTG events related to plug insertion or removal
sl@0: 		*/
sl@0: 		EEventAPlugInserted			= ( 1 << EEventIndexAPlugInserted		),
sl@0: 		EEventAPlugRemoved			= ( 1 << EEventIndexAPlugRemoved		),
sl@0: 
sl@0: 		EEventGroupPlugChanges		= ( EEventAPlugInserted
sl@0: 									   |EEventAPlugRemoved
sl@0: 									  ),
sl@0: 
sl@0: 		/**
sl@0: 		OTG events relating to changes visible on the bus
sl@0: 		*/
sl@0: 		EEventVbusRaised			= ( 1 << EEventIndexVbusRaised			),
sl@0: 		EEventVbusDropped			= ( 1 << EEventIndexVbusDropped			),
sl@0: 
sl@0: 		EEventSrpInitiated			= ( 1 << EEventIndexSrpInitiated		),
sl@0: 
sl@0: 		EEventSrpReceived			= ( 1 << EEventIndexSrpReceived			),
sl@0: 		EEventHnpEnabled			= ( 1 << EEventIndexHnpEnabled			),
sl@0: 		EEventHnpDisabled			= ( 1 << EEventIndexHnpDisabled			),
sl@0: 		EEventHnpSupported			= ( 1 << EEventIndexHnpSupported		),
sl@0: 		EEventHnpAltSupported		= ( 1 << EEventIndexHnpAltSupported		),
sl@0: 
sl@0: 		EEventBusConnectionBusy		= ( 1 << EEventIndexBusConnectionBusy	),
sl@0: 		EEventBusConnectionIdle		= ( 1 << EEventIndexBusConnectionIdle	),
sl@0: 
sl@0: 		EEventGroupBusChanges		= ( EEventVbusRaised
sl@0: 									   |EEventVbusDropped
sl@0: 									   |EEventSrpInitiated
sl@0: 									   |EEventSrpReceived
sl@0: 									   |EEventHnpEnabled
sl@0: 									   |EEventHnpDisabled
sl@0: 									   |EEventHnpSupported	
sl@0: 									   |EEventHnpAltSupported
sl@0: 									   |EEventBusConnectionBusy
sl@0: 									   |EEventBusConnectionIdle
sl@0: 									  ),
sl@0: 
sl@0: 		/**
sl@0: 		OTG events related to changes in the current role the device
sl@0: 		is performing (independant of the orientation of the connection)
sl@0: 		*/
sl@0: 		EEventRoleChangedToHost		= ( 1 << EEventIndexRoleChangedToHost	),
sl@0: 		EEventRoleChangedToDevice	= ( 1 << EEventIndexRoleChangedToDevice	),
sl@0: 		EEventRoleChangedToIdle		= ( 1 << EEventIndexRoleChangedToIdle	),
sl@0: 
sl@0: 		EEventGroupRoleChanges		= ( EEventRoleChangedToHost
sl@0: 									   |EEventRoleChangedToDevice
sl@0: 									   |EEventRoleChangedToIdle
sl@0: 									  ),
sl@0: 
sl@0: 		/**
sl@0: 		Helpful macro to allow users to register for 'everything'
sl@0: 		*/
sl@0: 		EEventGroupAll				= ( EEventGroupPlugChanges
sl@0: 									   |EEventGroupBusChanges
sl@0: 									   |EEventGroupRoleChanges
sl@0: 									  )
sl@0: 		};
sl@0: 
sl@0: private:
sl@0: 
sl@0: 	/**
sl@0: 	OTG State, supplied in a form that will enable use as an array
sl@0: 	index (note also how this is used below in the bit-mask form)
sl@0: 	*/
sl@0: 	enum TOtgStateIndex
sl@0: 		{
sl@0: 		/**
sl@0: 		Single case of non-stable state, used only during
sl@0: 		startup
sl@0: 		*/
sl@0: 		EStateIndexReset = 0,
sl@0: 
sl@0: 		/**
sl@0: 		'A'-connection states (names are derived from OTG-Supplement
sl@0: 		Figure 6-2 On-The-Go A-Device State Diagram)
sl@0: 		*/
sl@0: 		EStateIndexAIdle,
sl@0: 		EStateIndexAHost,
sl@0: 		EStateIndexAPeripheral,
sl@0: 		EStateIndexAVbusError,
sl@0: 
sl@0: 		/**
sl@0: 		'B'-connection states (names are derived from OTG-Supplement
sl@0: 		Figure 6-3 On-The-Go B-Device State Diagram)
sl@0: 		*/
sl@0: 		EStateIndexBIdle,
sl@0: 		EStateIndexBPeripheral,
sl@0: 		EStateIndexBHost,
sl@0: 
sl@0: 		/**
sl@0: 		Single indicator used for array sizing
sl@0: 		*/
sl@0: 		EStateIndexNumStates
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	OTG State, supplied in a form that can be used to create a mask
sl@0: 	that can specify a watcher's states of interest.
sl@0: 	*/
sl@0: 	enum TOtgState
sl@0: 		{
sl@0: 		/**
sl@0: 		 * 'empty' dummy state
sl@0: 		 */
sl@0: 		EStateNotValid = 0,
sl@0: 		
sl@0: 		/**
sl@0: 		Single case of non-stable state, used only during
sl@0: 		startup
sl@0: 		*/
sl@0: 		EStateReset					= ( 1 << EStateIndexReset		),
sl@0: 
sl@0: 		/**
sl@0: 		'A'-connection states (names are derived from OTG-Supplement
sl@0: 		Figure 6-2 On-The-Go A-Device State Diagram)
sl@0: 		*/
sl@0: 		EStateAIdle					= ( 1 << EStateIndexAIdle		),
sl@0: 		EStateAHost					= ( 1 << EStateIndexAHost		),
sl@0: 		EStateAPeripheral			= ( 1 << EStateIndexAPeripheral	),
sl@0: 		EStateAVbusError			= ( 1 << EStateIndexAVbusError	),
sl@0: 
sl@0: 		EStateAllA					= ( EStateAIdle
sl@0: 									   |EStateAHost
sl@0: 									   |EStateAPeripheral
sl@0: 									   |EStateAVbusError
sl@0: 									  ),
sl@0: 
sl@0: 		EStateAllAExceptBusError	= ( EStateAIdle
sl@0: 									   |EStateAHost
sl@0: 									   |EStateAPeripheral
sl@0: 									  ),
sl@0: 
sl@0: 		/**
sl@0: 		'B'-connection states (names are derived from OTG-Supplement
sl@0: 		Figure 6-3 On-The-Go B-Device State Diagram)
sl@0: 		*/
sl@0: 		EStateBIdle					= ( 1 << EStateIndexBIdle		),
sl@0: 		EStateBPeripheral			= ( 1 << EStateIndexBPeripheral	),
sl@0: 		EStateBHost					= ( 1 << EStateIndexBHost		),
sl@0: 
sl@0: 		EStateAllB					= ( EStateBIdle
sl@0: 									   |EStateBPeripheral
sl@0: 									   |EStateBHost
sl@0: 									  )
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	OTG Messages, these can be retrieved to satisfy the OTG Supplement 
sl@0: 	"No Silent Failures" requirement.
sl@0: 
sl@0:     The error numbers are derived for constants set up in d32otgdi_error.h
sl@0: 	and are used here so that the enumerator can be used to enforce compiler
sl@0: 	checks on the functions that handle the messages.
sl@0: 
sl@0:     Note that this minimal set of message events only contains the few
sl@0: 	things that are reported by the USB OTG Stack: it is expected that 
sl@0: 	these will be merged into a composite message event flow by USBMAN
sl@0: 	*/
sl@0: 	enum TOtgMessage
sl@0: 		{
sl@0: 		/**
sl@0: 		Internal OTGDI errors must also be offered to USBMAN in order to
sl@0: 		fully support the "No Silent Failures" policy
sl@0: 		*/
sl@0: 		EEventQueueOverflow					= KErrUsbOtgEventQueueOverflow,	
sl@0: 		EStateQueueOverflow					= KErrUsbOtgStateQueueOverflow,
sl@0: 		EMessageQueueOverflow				= KErrUsbOtgMessageQueueOverflow,
sl@0: 
sl@0: 		EMessageBadState					= KErrUsbOtgBadState,
sl@0: 
sl@0: 		/**
sl@0: 		Errors relating to attempts to do wrong things to VBUS
sl@0: 		*/
sl@0: 		EMessageStackNotStarted				= KErrUsbOtgStackNotStarted,
sl@0: 		EMessageVbusAlreadyRaised			= KErrUsbOtgVbusAlreadyRaised,
sl@0: 		EMessageSrpForbidden				= KErrUsbOtgSrpForbidden,
sl@0: 
sl@0: 		/**
sl@0: 		Generic message that there has been some form of problem in
sl@0: 		the lower-level USB OTG stack's calls
sl@0: 		*/
sl@0: 		EMessageBusControlProblem			= KErrUsbOtgBusControlProblem,
sl@0: 
sl@0: 		/**
sl@0: 		Generic message that there has been a reportable failure in sending
sl@0: 		the B_HNP_ENABLE SetFeature command
sl@0: 		*/
sl@0: 		EMessageHnpEnableProblem			= KErrUsbOtgHnpEnableProblem,
sl@0: 		
sl@0: 		/**
sl@0: 		Peripheral reported as 'not-supported'
sl@0: 		*/
sl@0: 		EMessagePeriphNotSupported			= KErrUsbOtgPeriphNotSupported,
sl@0: 		
sl@0: 		/**
sl@0: 		Individual error messages 
sl@0: 		*/
sl@0: 		EMessageVbusError					= KErrUsbOtgVbusError,
sl@0: 		EMessageSrpTimeout					= KErrUsbOtgSrpTimeout,
sl@0: 		EMessageSrpActive					= KErrUsbOtgSrpActive,
sl@0: 		EMessageSrpNotPermitted				= KErrUsbOtgSrpNotPermitted,
sl@0: 		EMessageHnpNotPermitted				= KErrUsbOtgHnpNotPermitted,
sl@0: 		EMessageHnpNotEnabled				= KErrUsbOtgHnpNotEnabled,
sl@0: 		EMessageHnpNotSuspended				= KErrUsbOtgHnpNotSuspended,
sl@0: 		EMessageVbusPowerUpNotPermitted		= KErrUsbOtgVbusPowerUpNotPermitted,
sl@0: 		EMessageVbusPowerUpError			= KErrUsbOtgVbusPowerUpError,
sl@0: 		EMessageVbusPowerDownNotPermitted	= KErrUsbOtgVbusPowerDownNotPermitted,
sl@0: 		EMessageVbusClearErrorNotPermitted	= KErrUsbOtgVbusClearErrorNotPermitted,
sl@0: 		EMessageHnpNotResponding			= KErrUsbOtgHnpNotResponding,
sl@0: 		EMessageHnpBusDrop					= KErrUsbOtgHnpBusDrop
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	/**
sl@0: 	Set of OTG operations required for use of the User-Kernel channel
sl@0: 	*/
sl@0: 	enum TOtgRequest
sl@0: 		{
sl@0: 		EQueueOtgEventRequest = 0,
sl@0: 		EQueueOtgStateRequest,
sl@0: 		EQueueOtgMessageRequest,
sl@0: 
sl@0: 		EQueueOtgIdPinNotification,
sl@0: 		EQueueOtgVbusNotification,
sl@0: 		EQueueOtgConnectionNotification,
sl@0: 		EQueueOtgStateNotification,
sl@0: 		};
sl@0: 
sl@0: 	enum TOtgControl
sl@0: 		{
sl@0: 		EActivateOptTestMode = 0,
sl@0: 
sl@0: 		EStartStacks,
sl@0: 		EStopStacks,
sl@0: 
sl@0: 		ECancelOtgEventRequest,
sl@0: 		ECancelOtgStateRequest,
sl@0: 		ECancelOtgMessageRequest,
sl@0: 
sl@0: 		ECancelOtgIdPinNotification,
sl@0: 		ECancelOtgVbusNotification,
sl@0: 		ECancelOtgConnectionNotification,
sl@0: 		ECancelOtgStateNotification,
sl@0: 
sl@0: 		EBusRequest,
sl@0: 		EBusRespondSrp,
sl@0: 		EBusDrop,
sl@0: 		EBusClearError
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	ID-Pin possible states (note that this is not a plain boolean, to
sl@0: 	allow for future expansion to cover car-kit - if this is needed, then
sl@0: 	a new enum value of 'EIdPinCarKit' should be inserted)
sl@0: 	*/
sl@0: 	enum TOtgIdPin
sl@0: 		{
sl@0: 		EIdPinAPlug = 0,
sl@0: 		EIdPinBPlug,
sl@0: 		
sl@0: 		// deprecated EIdPinCarKit - to be removed after OTGDI reaches MCL
sl@0: 		
sl@0: 		EIdPinCarKit,
sl@0: 
sl@0: 		EIdPinUnknown
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	VBUS voltage level possible states (as detected from an OTG transceiver)
sl@0: 	*/
sl@0: 	enum TOtgVbus
sl@0: 		{
sl@0: 		EVbusHigh = 0,
sl@0: 		EVbusLow,
sl@0: 
sl@0: 		EVbusUnknown
sl@0: 		};
sl@0: 		
sl@0: 	/**
sl@0: 	Connection 'Idle' indicator (potential to drop VBUS)
sl@0: 	*/
sl@0: 	enum TOtgConnection
sl@0: 		{
sl@0: 		EConnectionBusy = 0,
sl@0: 		EConnectionIdle,
sl@0: 		
sl@0: 		EConnectionUnknown
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	inline static const TDesC& Name();
sl@0: 	inline static TVersion VersionRequired();
sl@0: 
sl@0: #ifndef __KERNEL_MODE__
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	inline TInt Open();
sl@0: 
sl@0: 	inline TInt ActivateOptTestMode();
sl@0: 
sl@0: 	inline TInt StartStacks();
sl@0: 	inline void StopStacks();
sl@0: 
sl@0: 	inline void QueueOtgEventRequest(TOtgEvent& aOldestEvent, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgEventRequest();
sl@0: 
sl@0: 	inline void QueueOtgStateRequest(TOtgState& aState, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgStateRequest();
sl@0: 
sl@0: 	inline void QueueOtgMessageRequest(TOtgMessage& aMessage, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgMessageRequest();
sl@0: 
sl@0: 	inline void QueueOtgIdPinNotification(TOtgIdPin& aCurrentIdPin, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgIdPinNotification();
sl@0: 
sl@0: 	inline void QueueOtgVbusNotification(TOtgVbus& aCurrentVbus, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgVbusNotification();
sl@0: 
sl@0: 	inline void QueueOtgConnectionNotification(TOtgConnection& aCurrentConnection, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgConnectionNotification();
sl@0: 
sl@0: 	inline void QueueOtgStateNotification(TOtgState& aCurrentState, TRequestStatus& aStatus);
sl@0: 	inline void CancelOtgStateNotification();
sl@0: 
sl@0: 	inline TInt BusRequest();
sl@0: 	inline TInt BusRespondSrp();
sl@0: 	inline TInt BusDrop();
sl@0: 	inline TInt BusClearError();
sl@0: 
sl@0: #endif // !__KERNEL_MODE__
sl@0: 	};
sl@0: 
sl@0: #include <d32otgdi.inl>
sl@0: 
sl@0: #endif // D32OTGDI_H