1 // Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 /**

    17  @file

    18  @internalTechnology

    19  @prototype

    20 */

    21 

    22 #ifndef D32OTGDI_H

    23 #define D32OTGDI_H

    24 

    25 #ifdef __KERNEL_MODE__

    26 #  include <kernel/klib.h>

    27 #  include <e32ver.h>

    28 #else

    29 #  include <e32base.h>

    30 #  include <e32ver.h>

    31 #  include <e32debug.h>

    32 #endif

    33 

    34 #include <d32otgdi_errors.h>

    35 

    36 /**

    37 The bi-directional interface which USB Manager uses to talk to OTGDI about 

    38 OTG related issues

    39 

    40 @note This API is only available to USBMAN, a restriction which is enforced 

    41 by checking the SID of the calling process.

    42 */

    43 NONSHARABLE_CLASS(RUsbOtgDriver) : public RBusLogicalChannel

    44 	{

    45 	friend class DUsbOtgDriver;

    46 

    47 public:

    48 

    49 	// Version number history:

    50 	//

    51 	// PREQ1782 = 1.0

    52 	// PREQ1305 = 1.1

    53 	

    54 	static const TInt KMajorVersionNumber = 1;

    55 	static const TInt KMinorVersionNumber = 1;

    56 

    57 private:

    58 	

    59 	/**

    60 	OTG Event, supplied in a form that will enable use as an array

    61 	index (note also how this is used below in the bit-mask form,

    62 	but that this is only extended to a few, other events are OTG

    63 	internal and used only to drive the local state machine)

    64 	*/

    65 	enum TOtgEventIndex

    66 		{

    67 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **

    68 		'public' OTG events

    69 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */

    70 

    71 		/**

    72 		OTG events related to plug insertion or removal

    73 		*/

    74 		EEventIndexAPlugInserted = 0,

    75 		EEventIndexAPlugRemoved,

    76 

    77 		/**

    78 		OTG events relating to changes visible on the bus

    79 		*/

    80 		EEventIndexVbusRaised,

    81 		EEventIndexVbusDropped,

    82 		

    83 		EEventIndexSrpInitiated,

    84 

    85 		EEventIndexSrpReceived,

    86 		EEventIndexHnpEnabled,

    87 		EEventIndexHnpDisabled,

    88 		EEventIndexHnpSupported,

    89 		EEventIndexHnpAltSupported,

    90 

    91 		EEventIndexBusConnectionBusy,

    92 		EEventIndexBusConnectionIdle,

    93 		

    94 		/**

    95 		OTG events related to changes in the current role the device

    96 		is performing (independant of the orientation of the connection)

    97 		*/

    98 		EEventIndexRoleChangedToHost,

    99 		EEventIndexRoleChangedToDevice,

   100 		EEventIndexRoleChangedToIdle,

   101 

   102 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **

   103 		'private' OTG events - these are not converted to the bit-map form,

   104 		but are used solely to stim the OTG state machine

   105 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */

   106 		

   107 		EEventIndexPrivateAfterThis,

   108 

   109 		EEventIndexVbusError,

   110 		EEventIndexClearVbusError,

   111 		

   112 		EEventIndexResetStateMachine,

   113 

   114 		EEventIndexNoEvent,

   115 

   116 		/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - **

   117 		Single indicator used for array sizing

   118 		** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */

   119 		EEventIndexNumEvents

   120 		};

   121 

   122 public:

   123 

   124 	/**

   125 	OTG Events, supplied in a form that can be used to create a mask

   126 	that can specify a watcher's events of interest.

   127 	*/

   128 	enum TOtgEvent

   129 		{

   130 		/**

   131 		 * 'empty' dummy event

   132 		 */

   133 		EEventNotValid = 0,

   134 		

   135 		/**

   136 		OTG events related to plug insertion or removal

   137 		*/

   138 		EEventAPlugInserted			= ( 1 << EEventIndexAPlugInserted		),

   139 		EEventAPlugRemoved			= ( 1 << EEventIndexAPlugRemoved		),

   140 

   141 		EEventGroupPlugChanges		= ( EEventAPlugInserted

   142 									   |EEventAPlugRemoved

   143 									  ),

   144 

   145 		/**

   146 		OTG events relating to changes visible on the bus

   147 		*/

   148 		EEventVbusRaised			= ( 1 << EEventIndexVbusRaised			),

   149 		EEventVbusDropped			= ( 1 << EEventIndexVbusDropped			),

   150 

   151 		EEventSrpInitiated			= ( 1 << EEventIndexSrpInitiated		),

   152 

   153 		EEventSrpReceived			= ( 1 << EEventIndexSrpReceived			),

   154 		EEventHnpEnabled			= ( 1 << EEventIndexHnpEnabled			),

   155 		EEventHnpDisabled			= ( 1 << EEventIndexHnpDisabled			),

   156 		EEventHnpSupported			= ( 1 << EEventIndexHnpSupported		),

   157 		EEventHnpAltSupported		= ( 1 << EEventIndexHnpAltSupported		),

   158 

   159 		EEventBusConnectionBusy		= ( 1 << EEventIndexBusConnectionBusy	),

   160 		EEventBusConnectionIdle		= ( 1 << EEventIndexBusConnectionIdle	),

   161 

   162 		EEventGroupBusChanges		= ( EEventVbusRaised

   163 									   |EEventVbusDropped

   164 									   |EEventSrpInitiated

   165 									   |EEventSrpReceived

   166 									   |EEventHnpEnabled

   167 									   |EEventHnpDisabled

   168 									   |EEventHnpSupported	

   169 									   |EEventHnpAltSupported

   170 									   |EEventBusConnectionBusy

   171 									   |EEventBusConnectionIdle

   172 									  ),

   173 

   174 		/**

   175 		OTG events related to changes in the current role the device

   176 		is performing (independant of the orientation of the connection)

   177 		*/

   178 		EEventRoleChangedToHost		= ( 1 << EEventIndexRoleChangedToHost	),

   179 		EEventRoleChangedToDevice	= ( 1 << EEventIndexRoleChangedToDevice	),

   180 		EEventRoleChangedToIdle		= ( 1 << EEventIndexRoleChangedToIdle	),

   181 

   182 		EEventGroupRoleChanges		= ( EEventRoleChangedToHost

   183 									   |EEventRoleChangedToDevice

   184 									   |EEventRoleChangedToIdle

   185 									  ),

   186 

   187 		/**

   188 		Helpful macro to allow users to register for 'everything'

   189 		*/

   190 		EEventGroupAll				= ( EEventGroupPlugChanges

   191 									   |EEventGroupBusChanges

   192 									   |EEventGroupRoleChanges

   193 									  )

   194 		};

   195 

   196 private:

   197 

   198 	/**

   199 	OTG State, supplied in a form that will enable use as an array

   200 	index (note also how this is used below in the bit-mask form)

   201 	*/

   202 	enum TOtgStateIndex

   203 		{

   204 		/**

   205 		Single case of non-stable state, used only during

   206 		startup

   207 		*/

   208 		EStateIndexReset = 0,

   209 

   210 		/**

   211 		'A'-connection states (names are derived from OTG-Supplement

   212 		Figure 6-2 On-The-Go A-Device State Diagram)

   213 		*/

   214 		EStateIndexAIdle,

   215 		EStateIndexAHost,

   216 		EStateIndexAPeripheral,

   217 		EStateIndexAVbusError,

   218 

   219 		/**

   220 		'B'-connection states (names are derived from OTG-Supplement

   221 		Figure 6-3 On-The-Go B-Device State Diagram)

   222 		*/

   223 		EStateIndexBIdle,

   224 		EStateIndexBPeripheral,

   225 		EStateIndexBHost,

   226 

   227 		/**

   228 		Single indicator used for array sizing

   229 		*/

   230 		EStateIndexNumStates

   231 		};

   232 

   233 public:

   234 

   235 	/**

   236 	OTG State, supplied in a form that can be used to create a mask

   237 	that can specify a watcher's states of interest.

   238 	*/

   239 	enum TOtgState

   240 		{

   241 		/**

   242 		 * 'empty' dummy state

   243 		 */

   244 		EStateNotValid = 0,

   245 		

   246 		/**

   247 		Single case of non-stable state, used only during

   248 		startup

   249 		*/

   250 		EStateReset					= ( 1 << EStateIndexReset		),

   251 

   252 		/**

   253 		'A'-connection states (names are derived from OTG-Supplement

   254 		Figure 6-2 On-The-Go A-Device State Diagram)

   255 		*/

   256 		EStateAIdle					= ( 1 << EStateIndexAIdle		),

   257 		EStateAHost					= ( 1 << EStateIndexAHost		),

   258 		EStateAPeripheral			= ( 1 << EStateIndexAPeripheral	),

   259 		EStateAVbusError			= ( 1 << EStateIndexAVbusError	),

   260 

   261 		EStateAllA					= ( EStateAIdle

   262 									   |EStateAHost

   263 									   |EStateAPeripheral

   264 									   |EStateAVbusError

   265 									  ),

   266 

   267 		EStateAllAExceptBusError	= ( EStateAIdle

   268 									   |EStateAHost

   269 									   |EStateAPeripheral

   270 									  ),

   271 

   272 		/**

   273 		'B'-connection states (names are derived from OTG-Supplement

   274 		Figure 6-3 On-The-Go B-Device State Diagram)

   275 		*/

   276 		EStateBIdle					= ( 1 << EStateIndexBIdle		),

   277 		EStateBPeripheral			= ( 1 << EStateIndexBPeripheral	),

   278 		EStateBHost					= ( 1 << EStateIndexBHost		),

   279 

   280 		EStateAllB					= ( EStateBIdle

   281 									   |EStateBPeripheral

   282 									   |EStateBHost

   283 									  )

   284 		};

   285 

   286 public:

   287 

   288 	/**

   289 	OTG Messages, these can be retrieved to satisfy the OTG Supplement 

   290 	"No Silent Failures" requirement.

   291 

   292     The error numbers are derived for constants set up in d32otgdi_error.h

   293 	and are used here so that the enumerator can be used to enforce compiler

   294 	checks on the functions that handle the messages.

   295 

   296     Note that this minimal set of message events only contains the few

   297 	things that are reported by the USB OTG Stack: it is expected that 

   298 	these will be merged into a composite message event flow by USBMAN

   299 	*/

   300 	enum TOtgMessage

   301 		{

   302 		/**

   303 		Internal OTGDI errors must also be offered to USBMAN in order to

   304 		fully support the "No Silent Failures" policy

   305 		*/

   306 		EEventQueueOverflow					= KErrUsbOtgEventQueueOverflow,	

   307 		EStateQueueOverflow					= KErrUsbOtgStateQueueOverflow,

   308 		EMessageQueueOverflow				= KErrUsbOtgMessageQueueOverflow,

   309 

   310 		EMessageBadState					= KErrUsbOtgBadState,

   311 

   312 		/**

   313 		Errors relating to attempts to do wrong things to VBUS

   314 		*/

   315 		EMessageStackNotStarted				= KErrUsbOtgStackNotStarted,

   316 		EMessageVbusAlreadyRaised			= KErrUsbOtgVbusAlreadyRaised,

   317 		EMessageSrpForbidden				= KErrUsbOtgSrpForbidden,

   318 

   319 		/**

   320 		Generic message that there has been some form of problem in

   321 		the lower-level USB OTG stack's calls

   322 		*/

   323 		EMessageBusControlProblem			= KErrUsbOtgBusControlProblem,

   324 

   325 		/**

   326 		Generic message that there has been a reportable failure in sending

   327 		the B_HNP_ENABLE SetFeature command

   328 		*/

   329 		EMessageHnpEnableProblem			= KErrUsbOtgHnpEnableProblem,

   330 		

   331 		/**

   332 		Peripheral reported as 'not-supported'

   333 		*/

   334 		EMessagePeriphNotSupported			= KErrUsbOtgPeriphNotSupported,

   335 		

   336 		/**

   337 		Individual error messages 

   338 		*/

   339 		EMessageVbusError					= KErrUsbOtgVbusError,

   340 		EMessageSrpTimeout					= KErrUsbOtgSrpTimeout,

   341 		EMessageSrpActive					= KErrUsbOtgSrpActive,

   342 		EMessageSrpNotPermitted				= KErrUsbOtgSrpNotPermitted,

   343 		EMessageHnpNotPermitted				= KErrUsbOtgHnpNotPermitted,

   344 		EMessageHnpNotEnabled				= KErrUsbOtgHnpNotEnabled,

   345 		EMessageHnpNotSuspended				= KErrUsbOtgHnpNotSuspended,

   346 		EMessageVbusPowerUpNotPermitted		= KErrUsbOtgVbusPowerUpNotPermitted,

   347 		EMessageVbusPowerUpError			= KErrUsbOtgVbusPowerUpError,

   348 		EMessageVbusPowerDownNotPermitted	= KErrUsbOtgVbusPowerDownNotPermitted,

   349 		EMessageVbusClearErrorNotPermitted	= KErrUsbOtgVbusClearErrorNotPermitted,

   350 		EMessageHnpNotResponding			= KErrUsbOtgHnpNotResponding,

   351 		EMessageHnpBusDrop					= KErrUsbOtgHnpBusDrop

   352 		};

   353 

   354 public:

   355 

   356 	/**

   357 	Set of OTG operations required for use of the User-Kernel channel

   358 	*/

   359 	enum TOtgRequest

   360 		{

   361 		EQueueOtgEventRequest = 0,

   362 		EQueueOtgStateRequest,

   363 		EQueueOtgMessageRequest,

   364 

   365 		EQueueOtgIdPinNotification,

   366 		EQueueOtgVbusNotification,

   367 		EQueueOtgConnectionNotification,

   368 		EQueueOtgStateNotification,

   369 		};

   370 

   371 	enum TOtgControl

   372 		{

   373 		EActivateOptTestMode = 0,

   374 

   375 		EStartStacks,

   376 		EStopStacks,

   377 

   378 		ECancelOtgEventRequest,

   379 		ECancelOtgStateRequest,

   380 		ECancelOtgMessageRequest,

   381 

   382 		ECancelOtgIdPinNotification,

   383 		ECancelOtgVbusNotification,

   384 		ECancelOtgConnectionNotification,

   385 		ECancelOtgStateNotification,

   386 

   387 		EBusRequest,

   388 		EBusRespondSrp,

   389 		EBusDrop,

   390 		EBusClearError

   391 		};

   392 

   393 	/**

   394 	ID-Pin possible states (note that this is not a plain boolean, to

   395 	allow for future expansion to cover car-kit - if this is needed, then

   396 	a new enum value of 'EIdPinCarKit' should be inserted)

   397 	*/

   398 	enum TOtgIdPin

   399 		{

   400 		EIdPinAPlug = 0,

   401 		EIdPinBPlug,

   402 		

   403 		// deprecated EIdPinCarKit - to be removed after OTGDI reaches MCL

   404 		

   405 		EIdPinCarKit,

   406 

   407 		EIdPinUnknown

   408 		};

   409 

   410 	/**

   411 	VBUS voltage level possible states (as detected from an OTG transceiver)

   412 	*/

   413 	enum TOtgVbus

   414 		{

   415 		EVbusHigh = 0,

   416 		EVbusLow,

   417 

   418 		EVbusUnknown

   419 		};

   420 		

   421 	/**

   422 	Connection 'Idle' indicator (potential to drop VBUS)

   423 	*/

   424 	enum TOtgConnection

   425 		{

   426 		EConnectionBusy = 0,

   427 		EConnectionIdle,

   428 		

   429 		EConnectionUnknown

   430 		};

   431 

   432 public:

   433 

   434 	inline static const TDesC& Name();

   435 	inline static TVersion VersionRequired();

   436 

   437 #ifndef __KERNEL_MODE__

   438 

   439 public:

   440 

   441 	inline TInt Open();

   442 

   443 	inline TInt ActivateOptTestMode();

   444 

   445 	inline TInt StartStacks();

   446 	inline void StopStacks();

   447 

   448 	inline void QueueOtgEventRequest(TOtgEvent& aOldestEvent, TRequestStatus& aStatus);

   449 	inline void CancelOtgEventRequest();

   450 

   451 	inline void QueueOtgStateRequest(TOtgState& aState, TRequestStatus& aStatus);

   452 	inline void CancelOtgStateRequest();

   453 

   454 	inline void QueueOtgMessageRequest(TOtgMessage& aMessage, TRequestStatus& aStatus);

   455 	inline void CancelOtgMessageRequest();

   456 

   457 	inline void QueueOtgIdPinNotification(TOtgIdPin& aCurrentIdPin, TRequestStatus& aStatus);

   458 	inline void CancelOtgIdPinNotification();

   459 

   460 	inline void QueueOtgVbusNotification(TOtgVbus& aCurrentVbus, TRequestStatus& aStatus);

   461 	inline void CancelOtgVbusNotification();

   462 

   463 	inline void QueueOtgConnectionNotification(TOtgConnection& aCurrentConnection, TRequestStatus& aStatus);

   464 	inline void CancelOtgConnectionNotification();

   465 

   466 	inline void QueueOtgStateNotification(TOtgState& aCurrentState, TRequestStatus& aStatus);

   467 	inline void CancelOtgStateNotification();

   468 

   469 	inline TInt BusRequest();

   470 	inline TInt BusRespondSrp();

   471 	inline TInt BusDrop();

   472 	inline TInt BusClearError();

   473 

   474 #endif // !__KERNEL_MODE__

   475 	};

   476 

   477 #include <d32otgdi.inl>

   478 

   479 #endif // D32OTGDI_H