kernel/eka/include/drivers/usbcshared.h
changeset 0 a41df078684a
child 19 4a8fed1c0ef6
equal deleted inserted replaced
-1:000000000000 0:a41df078684a
       
     1 // Copyright (c) 2000-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 // e32\include\drivers\usbcshared.h
       
    15 // Kernel side definitions for the USB Device driver stack (PIL + LDD).
       
    16 // 
       
    17 //
       
    18 
       
    19 /**
       
    20  @file usbcshared.h
       
    21  @internalTechnology
       
    22 */
       
    23 
       
    24 #ifndef __USBCSHARED_H__
       
    25 #define __USBCSHARED_H__
       
    26 
       
    27 #include <drivers/usbcque.h>
       
    28 
       
    29 // Define here what options are required:
       
    30 // (USB_SUPPORTS_CONTROLENDPOINTS and USB_SUPPORTS_SET_DESCRIPTOR_REQUEST
       
    31 //  have never been tested though...)
       
    32 //#define USB_SUPPORTS_CONTROLENDPOINTS
       
    33 //#define USB_SUPPORTS_SET_DESCRIPTOR_REQUEST
       
    34 
       
    35 #include <drivers/usbcdesc.h>
       
    36 
       
    37 // Debug Support
       
    38 
       
    39 // Use for debugging purposes only (commented out for normal operation):
       
    40 //#define USBC_LDD_BUFFER_TRACE
       
    41 
       
    42 static const char KUsbPILPanicCat[] = "USB PIL FAULT"; // kernel fault category
       
    43 _LIT(KUsbPILKillCat, "USB PIL KILL");					// thread kill category
       
    44 _LIT(KUsbLDDKillCat, "USB LDD KILL");					// thread kill category
       
    45 
       
    46 /** Error code for stalled endpoint.
       
    47 */
       
    48 const TInt KErrEndpointStall = KErrLocked;
       
    49 
       
    50 /** Error code for Ep0 write prematurely ended by a host OUT token.
       
    51 */
       
    52 const TInt KErrPrematureEnd = KErrDiskFull;
       
    53 
       
    54 /** The following constants control the buffer arrangement for OUT transfers (IN transfers have only 1
       
    55 	buffer). The total size of buffering for an OUT endpoint will be number of buffers * buffersize,
       
    56 	so that, for example, a Bulk OUT endpoint will have KUsbcDmaBufNumBulk * KUsbcDmaBufSzBulk bytes of
       
    57 	buffering.
       
    58 	These buffers will be physically contiguous, so that DMA may be used.
       
    59 	The number of buffers MUST be >=2 - otherwise the buffering scheme won't work.
       
    60 	The buffer sizes should be an exact fraction of 4kB and the number of buffers such that the
       
    61 	buffersize * number of buffers is an exact multiple of 4kB, otherwise memory will be wasted.
       
    62 */
       
    63 /** Size of a Control ep buffer.
       
    64 */
       
    65 const TInt KUsbcDmaBufSzControl = 1024;
       
    66 
       
    67 /** Size of a Bulk ep buffer.
       
    68 */
       
    69 const TInt KUsbcDmaBufSzBulk = 4096;
       
    70 
       
    71 /** Size of an Interrupt ep buffer.
       
    72 */
       
    73 const TInt KUsbcDmaBufSzInterrupt = 4096;
       
    74 
       
    75 /** Size of an Isochronous ep buffer.
       
    76 */
       
    77 const TInt KUsbcDmaBufSzIsochronous = 4096;
       
    78 
       
    79 /** Number of buffers for Control OUT endpoints.
       
    80 */
       
    81 const TInt KUsbcDmaBufNumControl = 2;
       
    82 
       
    83 /** Number of buffers for Isochronous OUT endpoints.
       
    84 */
       
    85 const TInt KUsbcDmaBufNumIsochronous = 2;
       
    86 
       
    87 /** Number of buffers for Bulk OUT endpoints.
       
    88 */
       
    89 const TInt KUsbcDmaBufNumBulk = 2;
       
    90 
       
    91 /** Number of buffers for Interrupt OUT endpoints.
       
    92 */
       
    93 const TInt KUsbcDmaBufNumInterrupt = 2;
       
    94 
       
    95 /** Maximum buffer number.
       
    96 */
       
    97 const TInt KUsbcDmaBufNumMax = MAX4(KUsbcDmaBufNumControl, KUsbcDmaBufNumIsochronous,
       
    98 									KUsbcDmaBufNumBulk, KUsbcDmaBufNumInterrupt);
       
    99 
       
   100 /** Maximum number of recorded packets possible.
       
   101 */
       
   102 const TUint KUsbcDmaBufMaxPkts = 2;
       
   103 
       
   104 /** Number of arrays.
       
   105 */
       
   106 const TInt KUsbcDmaBufNumArrays = 2;
       
   107 
       
   108 /** Max size that Ep0 packets might have.
       
   109 */
       
   110 const TInt KUsbcBufSzControl = 64;
       
   111 
       
   112 /** The Ep0 RX data collection buffer area.
       
   113 	(Arbitrary size, judged to be sufficient for SET_DESCRIPTOR requests)
       
   114 */
       
   115 const TInt KUsbcBufSz_Ep0Rx = 1024;
       
   116 
       
   117 /** The Ep0 TX buffer area.
       
   118 	(Size sufficient to hold as much data as can be requested via GET_DESCRIPTOR)
       
   119 */
       
   120 const TInt KUsbcBufSz_Ep0Tx = 1024 * 64; 
       
   121 
       
   122 
       
   123 /** The USB version the stack is compliant with: 2.0 (BCD).
       
   124 */
       
   125 const TUint16 KUsbcUsbVersion = 0x0200;
       
   126 
       
   127 /** Maximum number of endpoints an interface (i.e. LDD) may have.
       
   128 */
       
   129 const TInt KUsbcMaxEpNumber = 5;
       
   130 
       
   131 /** Status FIFO depth; enough for 2 complete configs.
       
   132 */
       
   133 const TInt KUsbDeviceStatusQueueDepth = 15;
       
   134 
       
   135 /** = 'no status info'.
       
   136 */
       
   137 const TUint32 KUsbDeviceStatusNull = 0xffffffffu;
       
   138 
       
   139 /** = 'no buffer available'.
       
   140 */
       
   141 const TInt KUsbcInvalidBufferIndex = -1;
       
   142 
       
   143 /** = 'no packet available'.
       
   144 */
       
   145 const TUint KUsbcInvalidPacketIndex = (TUint)(-1);
       
   146 
       
   147 /** = 'no drainable buffers'.
       
   148 */
       
   149 const TInt KUsbcInvalidDrainQueueIndex = -1;
       
   150 
       
   151 /** Number of possible bandwidth priorities.
       
   152 */
       
   153 const TInt KUsbcDmaBufMaxPriorities = 4;
       
   154 
       
   155 // The following buffer sizes are used within the LDD for the different
       
   156 // user-selectable endpoint bandwidth priorities
       
   157 // (EUsbcBandwidthOUTDefault/Plus1/Plus2/Maximum + the same for 'IN').
       
   158 // These values, in particular those for the Maximum setting, were obtained
       
   159 // empirically.
       
   160 
       
   161 /** Bulk IN buffer sizes for different priorities (4K, 16K, 64K, 512K).
       
   162 */
       
   163 const TInt KUsbcDmaBufSizesBulkIN[KUsbcDmaBufMaxPriorities] =
       
   164 	{KUsbcDmaBufSzBulk, 0x4000, 0x10000, 0x80000};
       
   165 
       
   166 /** Bulk OUT buffer sizes for different priorities (4K, 16K, 64K, 512K).
       
   167 */
       
   168 const TInt KUsbcDmaBufSizesBulkOUT[KUsbcDmaBufMaxPriorities] =
       
   169 	{KUsbcDmaBufSzBulk, 0x4000, 0x10000, 0x80000};
       
   170 
       
   171 /** Number of UDCs supported in the system.
       
   172 	(Support for more than one UDC is preliminary.)
       
   173 */
       
   174 const TInt KUsbcMaxUdcs = 2;
       
   175 
       
   176 /** Number of endpoints a USB device can have.
       
   177 	(30 regular endpoints + 2 x Ep0)
       
   178 */
       
   179 const TInt KUsbcEpArraySize = KUsbcMaxEndpoints + 2;
       
   180 
       
   181 /** Number of notification requests of the same kind that can be registered at
       
   182 	a time. As normally not more than one request per kind per LDD is
       
   183 	permitted, this number is roughly equivalent to the maximum number of LDDs
       
   184 	that can be operating at the same time.
       
   185 	This constant is used by the PIL while maintaining its request lists
       
   186 	(iClientCallbacks, iStatusCallbacks, iEpStatusCallbacks, iOtgCallbacks) to
       
   187 	ensure that the lists are of a finite length and thus the list traverse
       
   188 	time is bounded.
       
   189 	This value is chosen with the maximum number of USB interfaces (not
       
   190 	settings) allowed by the spec for a single device in mind.
       
   191 */
       
   192 const TInt KUsbcMaxListLength = 256;
       
   193 
       
   194 /** Used by the LDD.
       
   195 */
       
   196 typedef TUint32 TUsbcPacketArray;
       
   197 
       
   198 
       
   199 /** Used as a return value from DUsbClientController::EnquireEp0NextState(),
       
   200 	the purpose of which is to enable the PSL to find out what the next stage
       
   201 	will be for a newly received Setup packet.
       
   202 
       
   203 	The enum values are self-explanatory.
       
   204 
       
   205 	@publishedPartner
       
   206 	@released
       
   207 */
       
   208 enum TUsbcEp0State
       
   209 	{
       
   210 	EEp0StateDataIn,
       
   211 	EEp0StateDataOut,
       
   212 	EEp0StateStatusIn
       
   213 	};
       
   214 
       
   215 
       
   216 /** Used to show the direction of a transfer request to the Controller.
       
   217 
       
   218 	@see TUsbcRequestCallback
       
   219 */
       
   220 enum TTransferDirection {EControllerNone, EControllerRead, EControllerWrite};
       
   221 
       
   222 
       
   223 /** These event codes are used by the PSL to tell the PIL what has happened.
       
   224 
       
   225 	@publishedPartner
       
   226 	@released
       
   227 */
       
   228 enum TUsbcDeviceEvent
       
   229 	{
       
   230 	/** The USB Suspend bus state has been detected. */
       
   231 	EUsbEventSuspend,
       
   232 	/** USB Resume signalling has been detected. */
       
   233 	EUsbEventResume,
       
   234 	/** A USB Reset condition has been detected. */
       
   235 	EUsbEventReset,
       
   236 	/** Physical removal of the USB cable has been detected. */
       
   237 	EUsbEventCableRemoved,
       
   238 	/** Physical insertion of the USB cable has been detected. */
       
   239 	EUsbEventCableInserted
       
   240 	};
       
   241 
       
   242 
       
   243 /** USB LDD client callback.
       
   244 */
       
   245 class TUsbcClientCallback
       
   246     {
       
   247 public:
       
   248 	inline TUsbcClientCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);
       
   249 	inline DBase* Owner() const;
       
   250 	inline TInt DoCallback();
       
   251 	inline void Cancel();
       
   252 	inline void SetDfcQ(TDfcQue* aDfcQ);
       
   253 public:
       
   254 	/** Used by the PIL to queue callback objects into a TSglQue. */
       
   255 	TSglQueLink iLink;
       
   256 private:
       
   257 	DBase* iOwner;
       
   258 	TDfc iDfc;
       
   259     };
       
   260 
       
   261 
       
   262 /** The endpoint halt/clear_halt status.
       
   263 */
       
   264 class TUsbcEndpointStatusCallback
       
   265 	{
       
   266 public:
       
   267 	inline TUsbcEndpointStatusCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);
       
   268 	inline void SetState(TUint aState);
       
   269 	inline TUint State() const;
       
   270 	inline DBase* Owner() const;
       
   271 	inline TInt DoCallback();
       
   272 	inline void Cancel();
       
   273 	inline void SetDfcQ(TDfcQue* aDfcQ);
       
   274 public:
       
   275 	/** Used by the PIL to queue callback objects into a TSglQue. */
       
   276 	TSglQueLink iLink;
       
   277 private:
       
   278 	DBase* iOwner;
       
   279 	TDfc iDfc;
       
   280 	TUint iState;
       
   281 	};
       
   282 
       
   283 
       
   284 /** Maximum number of device status requests that can be queued at a time.
       
   285 	The value chosen is thought to be sufficient in all situations.
       
   286 */
       
   287 const TInt KUsbcDeviceStateRequests = 8;
       
   288 
       
   289 
       
   290 /** The USB device status.
       
   291 */
       
   292 class TUsbcStatusCallback
       
   293 	{
       
   294 public:
       
   295 	inline TUsbcStatusCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);
       
   296 	inline void SetState(TUsbcDeviceState aState);
       
   297 	inline TUsbcDeviceState State(TInt aIndex) const;
       
   298 	inline void ResetState();
       
   299 	inline DBase* Owner() const;
       
   300 	inline TInt DoCallback();
       
   301 	inline void Cancel();
       
   302 	inline void SetDfcQ(TDfcQue* aDfcQ);
       
   303 public:
       
   304 	/** Used by the PIL to queue callback objects into a TSglQue. */
       
   305 	TSglQueLink iLink;
       
   306 private:
       
   307 	DBase* iOwner;
       
   308 	TDfc iDfc;
       
   309 	TUsbcDeviceState iState[KUsbcDeviceStateRequests];
       
   310 	};
       
   311 
       
   312 
       
   313 /** A USB transfer request.
       
   314 
       
   315 	@publishedPartner
       
   316 	@released
       
   317 */
       
   318 class TUsbcRequestCallback
       
   319 	{
       
   320 public:
       
   321 	/** @internalTechnology */
       
   322 	inline TUsbcRequestCallback(const DBase* aOwner, TInt aEndpointNum, TDfcFn aDfcFunc,
       
   323 						 TAny* aEndpoint, TDfcQue* aDfcQ, TInt aPriority);
       
   324 	/** @internalTechnology	*/
       
   325 	inline ~TUsbcRequestCallback();
       
   326 	/** @internalTechnology	*/
       
   327 	inline void SetRxBufferInfo(TUint8* aBufferStart, TPhysAddr aBufferAddr,
       
   328 								TUsbcPacketArray* aPacketIndex, TUsbcPacketArray* aPacketSize,
       
   329 								TInt aLength);
       
   330 	/** @internalTechnology	*/
       
   331 	inline void SetTxBufferInfo(TUint8* aBufferStart, TPhysAddr aBufferAddr, TInt aLength);
       
   332 	/** @internalTechnology	*/
       
   333 	inline void SetTransferDirection(TTransferDirection aTransferDir);
       
   334 	/** @internalTechnology	*/
       
   335 	inline const DBase* Owner() const;
       
   336 	/** @internalTechnology	*/
       
   337 	inline TInt DoCallback();
       
   338 	/** @internalTechnology	*/
       
   339 	inline void Cancel();
       
   340 public:
       
   341 	/** Used by the PIL to queue callback objects into a TSglQue.
       
   342 		@internalTechnology
       
   343 	*/
       
   344 	TSglQueLink iLink;
       
   345 public:
       
   346 	/** The endpoint number. */
       
   347 	const TInt iEndpointNum;
       
   348 	/** The 'real' endpoint number, as used by the PDD. */
       
   349 	TInt iRealEpNum;
       
   350 	/** Indicates the LDD client for this transfer. */
       
   351 	const DBase* const iOwner;
       
   352 	/** DFC, used by PIL to call back the LDD when transfer completes to the LDD. */
       
   353 	TDfc iDfc;
       
   354 	/** Direction of transfer request. */
       
   355 	TTransferDirection iTransferDir;
       
   356 	/** Start address of this buffer. */
       
   357 	TUint8* iBufferStart;
       
   358 	/** Physical address of buffer start (used for DMA). */
       
   359 	TPhysAddr iBufferAddr;
       
   360 	/** Array of pointers into iBufferStart (actually TUsbcPacketArray (*)[]). */
       
   361 	TUsbcPacketArray* iPacketIndex;
       
   362 	/** Array of packet sizes (actually TUsbcPacketArray (*)[]). */
       
   363 	TUsbcPacketArray* iPacketSize;
       
   364 	/** Length in bytes of buffer (iBufferStart). */
       
   365 	TInt iLength;
       
   366 	/** For IN transfers, if a zlp might be required at the end of this transfer. */
       
   367 	TBool iZlpReqd;
       
   368 	/** Number of bytes transmitted; changed by the PSL. */
       
   369 	TUint iTxBytes;
       
   370 	/** Number of packets received (if it is a read); changed by the PSL. */
       
   371 	TUint iRxPackets;
       
   372 	/** The error code upon completion of the request; changed by the PSL. */
       
   373 	TInt iError;
       
   374 	};
       
   375 
       
   376 /** USB On-The-Go feature change callback.
       
   377 */
       
   378 class TUsbcOtgFeatureCallback
       
   379     {
       
   380 public:
       
   381 	inline TUsbcOtgFeatureCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);
       
   382 	inline void SetFeatures(TUint8 aFeatures);
       
   383 	inline TUint8 Features() const;
       
   384 	inline DBase* Owner() const;
       
   385 	inline TInt DoCallback();
       
   386 	inline void Cancel();
       
   387 	inline void SetDfcQ(TDfcQue* aDfcQ);
       
   388 public:
       
   389 	/** Used by the PIL to queue callback objects into a TSglQue. */
       
   390 	TSglQueLink iLink;
       
   391 private:
       
   392 	DBase* iOwner;
       
   393 	TDfc iDfc;
       
   394 	TUint8 iValue;
       
   395     };
       
   396 
       
   397 //
       
   398 //########################### Physical Device Driver (PIL + PSL) ######################
       
   399 //
       
   400 
       
   401 class TUsbcLogicalEndpoint;
       
   402 
       
   403 /** This models a physical (real) endpoint of the UDC.
       
   404 */
       
   405 class TUsbcPhysicalEndpoint
       
   406 	{
       
   407 public:
       
   408 	TUsbcPhysicalEndpoint();
       
   409 	~TUsbcPhysicalEndpoint();
       
   410 	TBool EndpointSuitable(const TUsbcEndpointInfo* aEpInfo, TInt aIfcNumber) const; // Check Todo, SC will pass pointer to derived class
       
   411 	TInt TypeAvailable(TUint aType) const;
       
   412 	TInt DirAvailable(TUint aDir) const;
       
   413 public:
       
   414 	/** This endpoint's capabilities. */
       
   415 	TUsbcEndpointCaps iCaps;
       
   416 	/** USB address: 0x00, 0x80, 0x01, 0x81, etc. */
       
   417 	TUint8 iEndpointAddr;
       
   418 	/** Pointer to interface # this endpoint has been assigned to. */
       
   419 	const TUint8* iIfcNumber;
       
   420 	/** Pointer to corresponding logical endpoint or NULL. */
       
   421 	const TUsbcLogicalEndpoint* iLEndpoint;
       
   422 	/** Only used when searching for available endpoints. */
       
   423 	TBool iSettingReserve;
       
   424 	/** True if endpoint is halted (i.e. issues STALL handshakes), false otherwise. */
       
   425 	TBool iHalt;
       
   426 	};
       
   427 
       
   428 
       
   429 class DUsbClientController;
       
   430 class TUsbcInterface;
       
   431 
       
   432 /** This is a 'logical' endpoint, as used by our device configuration model.
       
   433 */
       
   434 class TUsbcLogicalEndpoint
       
   435 	{
       
   436 public:
       
   437 	TUsbcLogicalEndpoint(DUsbClientController* aController, TUint aEndpointNum,
       
   438 						 const TUsbcEndpointInfo& aEpInfo, TUsbcInterface* aInterface,
       
   439 						 TUsbcPhysicalEndpoint* aPEndpoint);		// Check Todo, SC will pass pointer to derived class
       
   440 	~TUsbcLogicalEndpoint();
       
   441 public:
       
   442 	/** Pointer to controller object. */
       
   443 	DUsbClientController* iController;
       
   444 	/** The virtual (logical) endpoint number. */
       
   445 	const TInt iLEndpointNum;
       
   446 	/** This endpoint's info structure. */
       
   447 	TUsbcEndpointInfo iInfo;										// Check Todo, SC will pass pointer to derived class
       
   448 	/** Stores the endpoint size to be used for FS. */
       
   449 	TInt iEpSize_Fs;
       
   450 	/** Stores the endpoint size to be used for HS. */
       
   451 	TInt iEpSize_Hs;
       
   452 	/** 'Back' pointer. */
       
   453 	const TUsbcInterface* iInterface;
       
   454 	/** Pointer to corresponding physical endpoint, never NULL. */
       
   455 	TUsbcPhysicalEndpoint* const iPEndpoint;
       
   456 	};
       
   457 
       
   458 
       
   459 class TUsbcInterfaceSet;
       
   460 
       
   461 /** This is an 'alternate setting' of an interface.
       
   462 */
       
   463 class TUsbcInterface
       
   464 	{
       
   465 public:
       
   466 	TUsbcInterface(TUsbcInterfaceSet* aIfcSet, TUint8 aSetting, TBool aNoEp0Requests);
       
   467 	~TUsbcInterface();
       
   468 public:
       
   469 	/** Array of endpoints making up (belonging to) this setting. */
       
   470 	RPointerArray<TUsbcLogicalEndpoint> iEndpoints;
       
   471 	/** 'Back' pointer. */
       
   472 	TUsbcInterfaceSet* const iInterfaceSet;
       
   473 	/** bAlternateSetting (zero-based). */
       
   474 	const TUint8 iSettingCode;
       
   475 	/** KUsbcInterfaceInfo_NoEp0RequestsPlease: stall non-std Setup requests. */
       
   476 	const TBool iNoEp0Requests;
       
   477 	};
       
   478 
       
   479 
       
   480 /** This is an 'interface' (owning 1 or more alternate settings).
       
   481 
       
   482 	@see TUsbcInterface
       
   483 */
       
   484 class TUsbcInterfaceSet
       
   485 	{
       
   486 public:
       
   487 	TUsbcInterfaceSet(const DBase* aClientId, TUint8 aIfcNum);
       
   488 	~TUsbcInterfaceSet();
       
   489 	inline const TUsbcInterface* CurrentInterface() const;
       
   490 	inline TUsbcInterface* CurrentInterface();
       
   491 public:
       
   492 	/** Array of alternate settings provided by (belonging to) this interface. */
       
   493 	RPointerArray<TUsbcInterface> iInterfaces;
       
   494 	/** Pointer to the LDD which created and owns this interface. */
       
   495 	const DBase* const iClientId;
       
   496 	/** bInterfaceNumber (zero-based). */
       
   497 	TUint8 iInterfaceNumber;
       
   498 	/** bAlternateSetting (zero-based). */
       
   499 	TUint8 iCurrentInterface;
       
   500 	};
       
   501 
       
   502 
       
   503 /** This is a 'configuration' of the USB device.
       
   504 	Currently we support only one configuration.
       
   505 */
       
   506 class TUsbcConfiguration
       
   507 	{
       
   508 public:
       
   509 	TUsbcConfiguration(TUint8 aConfigVal);
       
   510 	~TUsbcConfiguration();
       
   511 public:
       
   512 	/** Array of interfaces making up (belonging to) this configuration. */
       
   513 	RPointerArray<TUsbcInterfaceSet> iInterfaceSets;
       
   514 	/** bConfigurationValue (one-based). */
       
   515 	const TUint8 iConfigValue;
       
   516 	};
       
   517 
       
   518 
       
   519 /** A USB Setup packet.
       
   520 
       
   521 	Used mainly internally by the PIL but also by
       
   522 	DUsbClientController::ProcessSetConfiguration(const TUsbcSetup&),
       
   523 	which is classified as publishedPartner.
       
   524 
       
   525 	@publishedPartner @released
       
   526 */
       
   527 struct TUsbcSetup
       
   528 	{
       
   529 	/** bmRequestType */
       
   530 	TUint8 iRequestType;
       
   531 	/** bRequest */
       
   532 	TUint8 iRequest;
       
   533 	/** wValue */
       
   534 	TUint16 iValue;
       
   535 	/** wIndex */
       
   536 	TUint16 iIndex;
       
   537 	/** wLength */
       
   538 	TUint16 iLength;
       
   539 	};
       
   540 
       
   541 
       
   542 /** The USB controller's power handler class.
       
   543 */
       
   544 class DUsbcPowerHandler : public DPowerHandler
       
   545 	{
       
   546 public:
       
   547 	void PowerUp();
       
   548 	void PowerDown(TPowerState);
       
   549 public:
       
   550 	DUsbcPowerHandler(DUsbClientController* aController);
       
   551 private:
       
   552 	DUsbClientController* iController;
       
   553 	};
       
   554 
       
   555 
       
   556 /*
       
   557 This is the EndpointInfo class used by the usb shared chunk client driver. 
       
   558 */
       
   559 
       
   560 class TUsbcScEndpointInfo;
       
   561 
       
   562 
       
   563 /**
       
   564 Used to represent an array of (or inheriting from) TUsbcEndpointInfo objects.
       
   565 
       
   566 @see DUsbClientController::SetInterface
       
   567 */
       
   568 
       
   569 class TUsbcEndpointInfoArray
       
   570 	{
       
   571 public:
       
   572 	typedef enum {EUsbcEndpointInfo, EUsbcScEndpointInfo} TArrayType;
       
   573 
       
   574 	TUsbcEndpointInfoArray(const TUsbcEndpointInfo* aData, TInt aDataSize=0);
       
   575 	TUsbcEndpointInfoArray(const TUsbcScEndpointInfo* aData, TInt aDataSize=0);
       
   576 	inline TUsbcEndpointInfo& operator[](TInt aIndex) const; 
       
   577 
       
   578 	TArrayType iType;
       
   579 private:
       
   580 	TUint8* iData;
       
   581 	TInt iDataSize;
       
   582 	};
       
   583 
       
   584 class TUsbcRequestCallback; // todo?? required only for class below
       
   585 
       
   586 /** The USB Device software controller class.
       
   587 
       
   588 	Implements the platform-independent layer (PIL), and defines the interface to the
       
   589 	platform-specific layer PSL).
       
   590 
       
   591 	The implementation of the platform-specific layer interfaces with the hardware.
       
   592 */
       
   593 class DUsbClientController : public DBase
       
   594 	{
       
   595 friend class DUsbcPowerHandler;
       
   596 friend TUsbcLogicalEndpoint::~TUsbcLogicalEndpoint();
       
   597 	//
       
   598 	// --- Platform Independent Layer (PIL) ---
       
   599 	//
       
   600 
       
   601 public:
       
   602 
       
   603 	//
       
   604 	// --- The following functions constitute the PIL interface to the LDD ---
       
   605 	//
       
   606 
       
   607 	virtual ~DUsbClientController();
       
   608 	IMPORT_C void DisableClientStack();
       
   609 	IMPORT_C void EnableClientStack();
       
   610 	IMPORT_C TBool IsActive();
       
   611 	IMPORT_C TInt RegisterClientCallback(TUsbcClientCallback& aCallback);
       
   612 	IMPORT_C static DUsbClientController* UsbcControllerPointer(TInt aUdc=0);
       
   613 	IMPORT_C void EndpointCaps(const DBase* aClientId, TDes8 &aCapsBuf) const;
       
   614 	IMPORT_C void DeviceCaps(const DBase* aClientId, TDes8 &aCapsBuf) const;
       
   615 	IMPORT_C TInt SetInterface(const DBase* aClientId, DThread* aThread, TInt aInterfaceNum,
       
   616 							   TUsbcClassInfo& aClass, TDesC8* aString, TInt aTotalEndpointsUsed,
       
   617 							   const TUsbcEndpointInfo aEndpointData[], TInt (*aRealEpNumbers)[6],
       
   618 							   TUint32 aFeatureWord);
       
   619 	IMPORT_C TInt SetInterface(const DBase* aClientId, DThread* aThread,
       
   620 												 TInt aInterfaceNum, TUsbcClassInfo& aClass,
       
   621 												 TDesC8* aString, TInt aTotalEndpointsUsed,
       
   622 												 const TUsbcEndpointInfoArray aEndpointData,
       
   623 												 TInt aRealEpNumbers[], TUint32 aFeatureWord);
       
   624 	IMPORT_C TInt ReleaseInterface(const DBase* aClientId, TInt aInterfaceNum);
       
   625 	IMPORT_C TInt ReEnumerate();
       
   626 	IMPORT_C TInt PowerUpUdc();
       
   627 	IMPORT_C TInt UsbConnect();
       
   628 	IMPORT_C TInt UsbDisconnect();
       
   629 	IMPORT_C TInt RegisterForStatusChange(TUsbcStatusCallback& aCallback);
       
   630 	IMPORT_C TInt DeRegisterForStatusChange(const DBase* aClientId);
       
   631 	IMPORT_C TInt RegisterForEndpointStatusChange(TUsbcEndpointStatusCallback& aCallback);
       
   632 	IMPORT_C TInt DeRegisterForEndpointStatusChange(const DBase* aClientId);
       
   633 	IMPORT_C TInt GetInterfaceNumber(const DBase* aClientId, TInt& aInterfaceNum) const;
       
   634 	IMPORT_C TInt DeRegisterClient(const DBase* aClientId);
       
   635 	IMPORT_C TInt Ep0PacketSize() const;
       
   636 	IMPORT_C TInt Ep0Stall(const DBase* aClientId);
       
   637 	IMPORT_C void SendEp0StatusPacket(const DBase* aClientId);
       
   638 	IMPORT_C TUsbcDeviceState GetDeviceStatus() const;
       
   639 	IMPORT_C TEndpointState GetEndpointStatus(const DBase* aClientId, TInt aEndpointNum) const;
       
   640 	IMPORT_C TInt SetupReadBuffer(TUsbcRequestCallback& aCallback);
       
   641 	IMPORT_C TInt SetupWriteBuffer(TUsbcRequestCallback& aCallback);
       
   642 	IMPORT_C void CancelReadBuffer(const DBase* aClientId, TInt aRealEndpoint);
       
   643 	IMPORT_C void CancelWriteBuffer(const DBase* aClientId, TInt aRealEndpoint);
       
   644 	IMPORT_C TInt HaltEndpoint(const DBase* aClientId, TInt aEndpointNum);
       
   645 	IMPORT_C TInt ClearHaltEndpoint(const DBase* aClientId, TInt aEndpointNum);
       
   646 	IMPORT_C TInt SetDeviceControl(const DBase* aClientId);
       
   647 	IMPORT_C TInt ReleaseDeviceControl(const DBase* aClientId);
       
   648 	IMPORT_C TUint EndpointZeroMaxPacketSizes() const;
       
   649 	IMPORT_C TInt SetEndpointZeroMaxPacketSize(TInt aMaxPacketSize);
       
   650 	IMPORT_C TInt GetDeviceDescriptor(DThread* aThread, TDes8& aDeviceDescriptor);
       
   651 	IMPORT_C TInt SetDeviceDescriptor(DThread* aThread, const TDes8& aDeviceDescriptor);
       
   652 	IMPORT_C TInt GetDeviceDescriptorSize(DThread* aThread, TDes8& aSize);
       
   653 	IMPORT_C TInt GetConfigurationDescriptor(DThread* aThread, TDes8& aConfigurationDescriptor);
       
   654 	IMPORT_C TInt SetConfigurationDescriptor(DThread* aThread, const TDes8& aConfigurationDescriptor);
       
   655 	IMPORT_C TInt GetConfigurationDescriptorSize(DThread* aThread, TDes8& aSize);
       
   656 	IMPORT_C TInt SetOtgDescriptor(DThread* aThread, const TDesC8& aOtgDesc);
       
   657 	IMPORT_C TInt GetOtgDescriptor(DThread* aThread, TDes8& aOtgDesc) const;
       
   658 	IMPORT_C TInt GetOtgFeatures(DThread* aThread, TDes8& aFeatures) const;
       
   659 	IMPORT_C TInt GetCurrentOtgFeatures(TUint8& aFeatures) const;
       
   660 	IMPORT_C TInt RegisterForOtgFeatureChange(TUsbcOtgFeatureCallback& aCallback);
       
   661 	IMPORT_C TInt DeRegisterForOtgFeatureChange(const DBase* aClientId);
       
   662 	IMPORT_C TInt GetInterfaceDescriptor(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   663 										 TDes8& aInterfaceDescriptor);
       
   664 	IMPORT_C TInt SetInterfaceDescriptor(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   665 										 const TDes8& aInterfaceDescriptor);
       
   666 	IMPORT_C TInt GetInterfaceDescriptorSize(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   667 											 TDes8& aSize);
       
   668 	IMPORT_C TInt GetEndpointDescriptor(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   669 										TInt aEndpointNum, TDes8& aEndpointDescriptor);
       
   670 	IMPORT_C TInt SetEndpointDescriptor(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   671 										TInt aEndpointNum, const TDes8& aEndpointDescriptor);
       
   672 	IMPORT_C TInt GetEndpointDescriptorSize(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   673 											TInt aEndpointNum, TDes8& aSize);
       
   674 	IMPORT_C TInt GetDeviceQualifierDescriptor(DThread* aThread, TDes8& aDeviceQualifierDescriptor);
       
   675 	IMPORT_C TInt SetDeviceQualifierDescriptor(DThread* aThread, const TDes8& aDeviceQualifierDescriptor);
       
   676 	IMPORT_C TInt GetOtherSpeedConfigurationDescriptor(DThread* aThread, TDes8& aConfigurationDescriptor);
       
   677 	IMPORT_C TInt SetOtherSpeedConfigurationDescriptor(DThread* aThread, const TDes8& aConfigurationDescriptor);
       
   678 	IMPORT_C TInt GetCSInterfaceDescriptorBlock(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   679 												TDes8& aInterfaceDescriptor);
       
   680 	IMPORT_C TInt SetCSInterfaceDescriptorBlock(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   681 												const TDes8& aInterfaceDescriptor, TInt aSize);
       
   682 	IMPORT_C TInt GetCSInterfaceDescriptorBlockSize(DThread* aThread, const DBase* aClientId,
       
   683 													TInt aSettingNum, TDes8& aSize);
       
   684 	IMPORT_C TInt GetCSEndpointDescriptorBlock(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   685 											   TInt aEndpointNum, TDes8& aEndpointDescriptor);
       
   686 	IMPORT_C TInt SetCSEndpointDescriptorBlock(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   687 											   TInt aEndpointNum, const TDes8& aEndpointDescriptor,
       
   688 											   TInt aSize);
       
   689 	IMPORT_C TInt GetCSEndpointDescriptorBlockSize(DThread* aThread, const DBase* aClientId, TInt aSettingNum,
       
   690 												   TInt aEndpointNum, TDes8& aSize);
       
   691 	IMPORT_C TInt GetStringDescriptorLangId(DThread* aThread, TDes8& aLangId);
       
   692 	IMPORT_C TInt SetStringDescriptorLangId(TUint16 aLangId);
       
   693 	IMPORT_C TInt GetManufacturerStringDescriptor(DThread* aThread, TDes8& aString);
       
   694 	IMPORT_C TInt SetManufacturerStringDescriptor(DThread* aThread, const TDes8& aString);
       
   695 	IMPORT_C TInt RemoveManufacturerStringDescriptor();
       
   696 	IMPORT_C TInt GetProductStringDescriptor(DThread* aThread, TDes8& aString);
       
   697 	IMPORT_C TInt SetProductStringDescriptor(DThread* aThread, const TDes8& aString);
       
   698 	IMPORT_C TInt RemoveProductStringDescriptor();
       
   699 	IMPORT_C TInt GetSerialNumberStringDescriptor(DThread* aThread, TDes8& aString);
       
   700 	IMPORT_C TInt SetSerialNumberStringDescriptor(DThread* aThread, const TDes8& aString);
       
   701 	IMPORT_C TInt RemoveSerialNumberStringDescriptor();
       
   702 	IMPORT_C TInt GetConfigurationStringDescriptor(DThread* aThread, TDes8& aString);
       
   703 	IMPORT_C TInt SetConfigurationStringDescriptor(DThread* aThread, const TDes8& aString);
       
   704 	IMPORT_C TInt RemoveConfigurationStringDescriptor();
       
   705 	IMPORT_C TInt GetStringDescriptor(DThread* aThread, TUint8 aIndex, TDes8& aString);
       
   706 	IMPORT_C TInt SetStringDescriptor(DThread* aThread, TUint8 aIndex, const TDes8& aString);
       
   707 	IMPORT_C TInt RemoveStringDescriptor(TUint8 aIndex);
       
   708 	IMPORT_C TInt AllocateEndpointResource(const DBase* aClientId, TInt aEndpointNum,
       
   709 										   TUsbcEndpointResource aResource);
       
   710 	IMPORT_C TInt DeAllocateEndpointResource(const DBase* aClientId, TInt aEndpointNum,
       
   711 											 TUsbcEndpointResource aResource);
       
   712 	IMPORT_C TBool QueryEndpointResource(const DBase* aClientId, TInt aEndpointNum,
       
   713 										 TUsbcEndpointResource aResource);
       
   714 	IMPORT_C TInt EndpointPacketSize(const DBase* aClientId, TInt aEndpointNum);
       
   715 
       
   716 	//
       
   717 	// --- Public (pure) virtual (implemented by PSL, used by LDD) ---
       
   718 	//
       
   719 
       
   720 	/** Forces the UDC into a non-idle state to perform a USB remote wakeup operation.
       
   721 
       
   722 		The PSL should first check the current value of iRmWakeupStatus_Enabled
       
   723 		to determine whether or not to actually send a Remote Wakeup.
       
   724 
       
   725 		@see iRmWakeupStatus_Enabled
       
   726 
       
   727 		@return KErrGeneral if Remote Wakeup feature is not enabled or an error is encountered,
       
   728 		KErrNone otherwise.
       
   729 
       
   730 		@publishedPartner @released
       
   731 	*/
       
   732 	IMPORT_C virtual TInt SignalRemoteWakeup() =0;
       
   733 
       
   734 	/** Dumps the contents of (all or part of) the UDC registers to the serial console.
       
   735 		This is for debugging purposes only.
       
   736 
       
   737 		@publishedPartner @released
       
   738 	*/
       
   739 	IMPORT_C virtual void DumpRegisters() =0;
       
   740 
       
   741 	/** Returns a pointer to the DFC queue that should be used by the USB LDD.
       
   742 
       
   743 		@return A pointer to the DFC queue that should be used by the USB LDD.
       
   744 
       
   745 		@publishedPartner @released
       
   746 	*/
       
   747 	IMPORT_C virtual TDfcQue* DfcQ(TInt aUnit) =0;
       
   748 
       
   749 	/** Returns information about the current operating speed of the UDC.
       
   750 
       
   751 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs.
       
   752 		 The default implementation in the PIL returns EFalse.)
       
   753 
       
   754 		@return ETrue if the UDC is currently operating at High speed, EFalse
       
   755 		otherwise (i.e. controller is operating at Full speed).
       
   756 
       
   757 		@publishedPartner @released
       
   758 	*/
       
   759 	IMPORT_C virtual TBool CurrentlyUsingHighSpeed();
       
   760 
       
   761 	//
       
   762 	// --- Public PIL functions ---
       
   763 	//
       
   764 
       
   765 	DUsbClientController* RegisterUdc(TInt aUdc);
       
   766 
       
   767 protected:
       
   768 
       
   769 	//
       
   770 	// --- Functions and data members provided by PIL, called by PSL ---
       
   771 	//
       
   772 
       
   773 	TBool InitialiseBaseClass(TUsbcDeviceDescriptor* aDeviceDesc,
       
   774 							  TUsbcConfigDescriptor* aConfigDesc,
       
   775 							  TUsbcLangIdDescriptor* aLangId,
       
   776 							  TUsbcStringDescriptor* aManufacturer =0,
       
   777 							  TUsbcStringDescriptor* aProduct =0,
       
   778 							  TUsbcStringDescriptor* aSerialNum =0,
       
   779 							  TUsbcStringDescriptor* aConfig =0,
       
   780 							  TUsbcOtgDescriptor* aOtgDesc =0);
       
   781 	DUsbClientController();
       
   782 	TInt DeviceEventNotification(TUsbcDeviceEvent aEvent);
       
   783 	void EndpointRequestComplete(TUsbcRequestCallback* aCallback);
       
   784 	TInt Ep0RequestComplete(TInt aRealEndpoint, TInt aCount, TInt aError);
       
   785 	void MoveToAddressState();
       
   786 	void SetCurrent(TInt aCurrent);
       
   787 	TUsbcEp0State EnquireEp0NextState(const TUint8* aSetupBuf) const;
       
   788 	TInt ProcessSetConfiguration(const TUsbcSetup& aPacket);
       
   789 	void HandleHnpRequest(TInt aHnpState);
       
   790 
       
   791 	/** This info can be used by the PSL before sending ZLPs.
       
   792 
       
   793 		@publishedPartner @released
       
   794 	*/
       
   795 	TBool iEp0ReceivedNonStdRequest;
       
   796 
       
   797 	/** True if RMW is currently enabled (set by either PIL or PSL).
       
   798 
       
   799 		@publishedPartner @released
       
   800 	*/
       
   801 	TBool iRmWakeupStatus_Enabled;
       
   802 
       
   803 	/** Ep0 incoming (rx) data is placed here (one packet).
       
   804 
       
   805 		@publishedPartner @released
       
   806 	*/
       
   807 	TUint8 iEp0_RxBuf[KUsbcBufSzControl];
       
   808 
       
   809 private:
       
   810 
       
   811 	//
       
   812 	// --- Platform Specific Layer (PSL) ---
       
   813 	//
       
   814 
       
   815 	/** This function will be called by the PIL upon decoding a SET_ADDRESS request.
       
   816 
       
   817 		UDCs which require a manual setting of the USB device address should do that in this function.
       
   818 
       
   819 		@param aAddress A valid USB device address that was received with the SET_ADDRESS request.
       
   820 
       
   821 		@return KErrNone if address was set successfully or if this UDC's address cannot be set manually,
       
   822 		KErrGeneral otherwise.
       
   823 
       
   824 		@publishedPartner @released
       
   825 	*/
       
   826 	virtual TInt SetDeviceAddress(TInt aAddress) =0;
       
   827 
       
   828 	/** Configures (enables) an endpoint (incl. Ep0) for data transmission or reception.
       
   829 
       
   830 		@param aRealEndpoint The number of the endpoint to be enabled.
       
   831 		@param aEndpointInfo A reference to a properly filled-in endpoint info structure.
       
   832 
       
   833 		@return KErrArgument if endpoint number or endpoint info invalid, KErrNone if endpoint
       
   834 		successfully configured, KErrGeneral otherwise.
       
   835 
       
   836 		@publishedPartner @released
       
   837 	*/
       
   838 	virtual TInt ConfigureEndpoint(TInt aRealEndpoint, const TUsbcEndpointInfo& aEndpointInfo) =0;
       
   839 
       
   840 	/** De-configures (disables) an endpoint (incl. Ep0).
       
   841 
       
   842 		@param aRealEndpoint The number of the endpoint to be disabled.
       
   843 
       
   844 		@return KErrArgument if endpoint number invalid, KErrNone if endpoint successfully de-configured,
       
   845 		KErrGeneral otherwise.
       
   846 
       
   847 		@publishedPartner @released
       
   848 	*/
       
   849 	virtual TInt DeConfigureEndpoint(TInt aRealEndpoint) =0;
       
   850 
       
   851 	/** Allocates an endpoint resource.
       
   852 
       
   853 		If the resource gets successfully allocated, it will be used from when the current bus transfer
       
   854 		has been completed.
       
   855 
       
   856 		@param aRealEndpoint The number of the endpoint.
       
   857 		@param aResource The endpoint resource to be allocated.
       
   858 
       
   859 		@return KErrNone if the resource has been successfully allocated, KErrNotSupported if the endpoint
       
   860 		does not support the resource requested, and KErrInUse if the resource is already consumed and
       
   861 		cannot be allocated.
       
   862 
       
   863 		@publishedPartner @deprecated
       
   864 	*/
       
   865 	virtual TInt AllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource) =0;
       
   866 
       
   867 	/** Deallocates (frees) an endpoint resource.
       
   868 
       
   869 		The resource will be removed from when the current bus transfer has been completed.
       
   870 
       
   871 		@param aRealEndpoint The number of the endpoint.
       
   872 		@param aResource The endpoint resource to be deallocated.
       
   873 
       
   874 		@return KErrNone if the resource has been successfully deallocated, KErrNotSupported if the endpoint
       
   875 		does not support the resource requested.
       
   876 
       
   877 		@publishedPartner @deprecated
       
   878 	*/
       
   879 	virtual TInt DeAllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource) =0;
       
   880 
       
   881 	/** Queries the use of and endpoint resource.
       
   882 
       
   883 		@param aRealEndpoint The number of the endpoint.
       
   884 		@param aResource The endpoint resource to be queried.
       
   885 
       
   886 		@return ETrue if the specified resource is in use at the endpoint, EFalse if not.
       
   887 
       
   888 		@publishedPartner @released
       
   889 	*/
       
   890 	virtual TBool QueryEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource) const =0;
       
   891 
       
   892 	/** Opens a DMA channel (if possible).
       
   893 
       
   894 		@param aRealEndpoint The number of the endpoint for which to open the DMA channel.
       
   895 
       
   896 		@return KErrArgument if endpoint number invalid, KErrNone if channel successfully opened or if
       
   897 		endpoint not DMA-capable, KErrGeneral otherwise.
       
   898 
       
   899 		@publishedPartner @released
       
   900 	*/
       
   901 	virtual TInt OpenDmaChannel(TInt aRealEndpoint);
       
   902 
       
   903 	/** Closes a DMA channel (if possible).
       
   904 
       
   905 		@param aRealEndpoint The number of the endpoint for which to close the DMA channel.
       
   906 
       
   907 		@publishedPartner @released
       
   908 	*/
       
   909 	virtual void CloseDmaChannel(TInt aRealEndpoint);
       
   910 
       
   911 	/** Sets up a read request on an endpoint (excl. Ep0) for data reception.
       
   912 
       
   913 		For endpoint 0 read requests, SetupEndpointZeroRead() is used instead.
       
   914 
       
   915 		@param aRealEndpoint The number of the endpoint to be used.
       
   916 		@param aCallback A reference to a properly filled-in request callback structure.
       
   917 
       
   918 		@return KErrArgument if endpoint number invalid, KErrNone if read successfully set up,
       
   919 		KErrGeneral otherwise.
       
   920 
       
   921 		@publishedPartner @released
       
   922 	*/
       
   923 	virtual TInt SetupEndpointRead(TInt aRealEndpoint, TUsbcRequestCallback& aCallback) =0;
       
   924 
       
   925 	/** Sets up a write request on an endpoint (excl. Ep0) for data transmission.
       
   926 
       
   927 		For endpoint 0 write requests, SetupEndpointZeroWrite() is used instead.
       
   928 
       
   929 		@param aRealEndpoint The number of the endpoint to be used.
       
   930 		@param aCallback A reference to a properly filled-in request callback structure.
       
   931 
       
   932 		@return KErrArgument if endpoint number invalid, KErrNone if write successfully set up,
       
   933 		KErrGeneral otherwise.
       
   934 
       
   935 		@publishedPartner @released
       
   936 	*/
       
   937 	virtual TInt SetupEndpointWrite(TInt aRealEndpoint, TUsbcRequestCallback& aCallback) =0;
       
   938 
       
   939 	/** Cancels a read request on an endpoint (excl. Ep0).
       
   940 
       
   941 		Note that endpoint 0 read requests are never cancelled by the PIL, so
       
   942 		there is also no CancelEndpointZeroRead() function.
       
   943 
       
   944 		@param aRealEndpoint The number of the endpoint to be used.
       
   945 
       
   946 		@return KErrArgument if endpoint number invalid, KErrNone if read successfully cancelled,
       
   947 		KErrGeneral otherwise.
       
   948 
       
   949 		@publishedPartner @released
       
   950 	*/
       
   951 	virtual TInt CancelEndpointRead(TInt aRealEndpoint) =0;
       
   952 
       
   953 	/** Cancels a write request on an endpoint (incl. Ep0).
       
   954 
       
   955 		The PIL calls this function also to cancel endpoint zero write requests.
       
   956 
       
   957 		@param aRealEndpoint The number of the endpoint to be used.
       
   958 
       
   959 		@return KErrArgument if endpoint number invalid, KErrNone if write successfully cancelled,
       
   960 		KErrGeneral otherwise.
       
   961 
       
   962 		@publishedPartner @released
       
   963 	*/
       
   964 	virtual TInt CancelEndpointWrite(TInt aRealEndpoint) =0;
       
   965 
       
   966 	/** Same as SetupEndpointRead(), but for endpoint zero only.
       
   967 
       
   968 		No callback is used here as this function is only used internally by the PIL and no user side request
       
   969 		exists for it. The data buffer to be used (filled) is iEp0_RxBuf.
       
   970 
       
   971 		@return KErrGeneral if (&iEndpoints[KEp0_Out]->iRxBuf != NULL) or some other error occurs,
       
   972 		KErrNone if read successfully set up.
       
   973 
       
   974 		@publishedPartner @released
       
   975 	*/
       
   976 	virtual TInt SetupEndpointZeroRead() =0;
       
   977 
       
   978 	/** Same as SetupEndpointWrite(), but for endpoint zero only.
       
   979 
       
   980 		No callback is used here as this function is only used internally by the PIL and no user side request
       
   981 		exists for it.
       
   982 
       
   983 		@param aBuffer This points to the beginning of the data to be sent.
       
   984 		@param aLength The number of bytes to be sent.
       
   985 		@param aZlpReqd ETrue if a zero-length packet (ZLP) is to be sent after the data.
       
   986 
       
   987 		@return KErrGeneral if (&iEndpoints[KEp0_In]->iTxBuf != NULL) or some other error occurs,
       
   988 		KErrNone if write successfully set up.
       
   989 
       
   990 		@publishedPartner @released
       
   991 	*/
       
   992 	virtual TInt SetupEndpointZeroWrite(const TUint8* aBuffer, TInt aLength, TBool aZlpReqd=EFalse) =0;
       
   993 
       
   994 	/** Sets up on Ep0 the transmission of a single zero-length packet (ZLP).
       
   995 
       
   996 		@return KErrNone if ZLP successfully set up, KErrGeneral otherwise..
       
   997 
       
   998 		@publishedPartner @released
       
   999 	*/
       
  1000 	virtual TInt SendEp0ZeroByteStatusPacket() =0;
       
  1001 
       
  1002 	/** Stalls an endpoint (incl. Ep0).
       
  1003 
       
  1004 		Isochronous endpoints cannot be stalled.
       
  1005 
       
  1006 		@param aRealEndpoint The number of the endpoint to be stalled.
       
  1007 
       
  1008 		@return KErrArgument if endpoint number invalid, KErrNone if endpoint successfully stalled,
       
  1009 		KErrGeneral otherwise.
       
  1010 
       
  1011 		@publishedPartner @released
       
  1012 	*/
       
  1013 	virtual TInt StallEndpoint(TInt aRealEndpoint) =0;
       
  1014 
       
  1015 	/** Clears the stall condition on an endpoint (incl. Ep0).
       
  1016 
       
  1017 		Isochronous endpoints cannot be stalled.
       
  1018 
       
  1019 		@param aRealEndpoint The number of the endpoint to be stalled.
       
  1020 
       
  1021 		@return KErrArgument if endpoint number invalid, KErrNone if endpoint successfully de-stalled,
       
  1022 		KErrGeneral otherwise.
       
  1023 
       
  1024 		@publishedPartner @released
       
  1025 	*/
       
  1026 	virtual TInt ClearStallEndpoint(TInt aRealEndpoint) =0;
       
  1027 
       
  1028 	/** Returns the stall status of an endpoint (incl. Ep0).
       
  1029 
       
  1030 		Isochronous endpoints cannot be stalled.
       
  1031 
       
  1032 		@param aRealEndpoint The number of the endpoint to be used.
       
  1033 
       
  1034 		@return KErrArgument if endpoint number invalid, 1 if endpoint is currently stalled, 0 if not.
       
  1035 
       
  1036 		@publishedPartner @released
       
  1037 	*/
       
  1038 	virtual TInt EndpointStallStatus(TInt aRealEndpoint) const =0;
       
  1039 
       
  1040 	/** Returns the error status of an endpoint (incl. Ep0).
       
  1041 
       
  1042 		@param aRealEndpoint The number of the endpoint to be used.
       
  1043 
       
  1044 		@return KErrArgument if endpoint number invalid, KErrNone if no error at this endpoint,
       
  1045 		KErrGeneral if there is an error.
       
  1046 
       
  1047 		@publishedPartner @released
       
  1048 	*/
       
  1049 	virtual TInt EndpointErrorStatus(TInt aRealEndpoint) const =0;
       
  1050 
       
  1051 	/** Resets the data toggle bit for an endpoint (incl. Ep0).
       
  1052 
       
  1053 		Isochronous endpoints don't use data toggles.
       
  1054 
       
  1055 		@param aRealEndpoint The number of the endpoint to be used.
       
  1056 
       
  1057 		@return KErrArgument if endpoint number invalid, KErrNone if data toggle successfully reset,
       
  1058 		KErrGeneral otherwise.
       
  1059 
       
  1060 		@publishedPartner @released
       
  1061 	*/
       
  1062 	virtual TInt ResetDataToggle(TInt aRealEndpoint) =0;
       
  1063 
       
  1064 	/** Returns the (11-bit) frame number contained in the last received SOF packet.
       
  1065 
       
  1066 		This information is used for isochronous transfers.
       
  1067 
       
  1068 		@return The (11-bit) frame number contained in the last received SOF packet.
       
  1069 
       
  1070 		@publishedPartner @released
       
  1071 	*/
       
  1072 	virtual TInt SynchFrameNumber() const =0;
       
  1073 
       
  1074 	/** Stores the (11-bit) frame number that should be sent in response to the next SYNCH_FRAME request(s).
       
  1075 
       
  1076 		@publishedPartner @released
       
  1077 	 */
       
  1078 	virtual void SetSynchFrameNumber(TInt aFrameNumber) =0;
       
  1079 
       
  1080 	/** Starts the UDC.
       
  1081 
       
  1082 		This initializes the device controller hardware before any other operation can be
       
  1083 		performed. Tasks to be carried out here might include
       
  1084 		- resetting the whole UDC design
       
  1085 		- enabling the UDC's clock
       
  1086 		- binding & enabling the UDC (primary) interrupt
       
  1087 		- write meaningful values to some general UDC registers
       
  1088 		- enabling the USB Reset interrupt
       
  1089 		- enabling the UDC proper (for instance by setting an Enable bit)
       
  1090 
       
  1091 		@return KErrNone if UDC successfully started, KErrGeneral if there was an error.
       
  1092 
       
  1093 		@publishedPartner @released
       
  1094 	*/
       
  1095 	virtual TInt StartUdc() =0;
       
  1096 
       
  1097 	/** Stops the UDC.
       
  1098 
       
  1099 		This basically makes undone what happened in StartUdc(). Tasks to be carried out
       
  1100 		here might include:
       
  1101 		- disabling the UDC proper (for instance by clearing an Enable bit)
       
  1102 		- disabling the USB Reset interrupt
       
  1103 		- disabling & unbinding the UDC (primary) interrupt
       
  1104 		- disabling the UDC's clock
       
  1105 
       
  1106 		@return KErrNone if UDC successfully stopped, KErrGeneral if there was an error.
       
  1107 
       
  1108 		@publishedPartner @released
       
  1109 	*/
       
  1110 	virtual TInt StopUdc() =0;
       
  1111 
       
  1112 	/** Connects the UDC  - and thus the USB device - physically to the bus.
       
  1113 
       
  1114 		This might involve a call into the Variant DLL, as the mechanism to achieve the connection can be
       
  1115 		specific to the platform (rather than UDC specific). Since this functionality is not part of the USB
       
  1116 		specification it has to be explicitly supported, either by the UDC itself or by the hardware
       
  1117 		platform. If it is supported, then the member function SoftConnectCaps should be implemented to return
       
  1118 		ETrue.
       
  1119 
       
  1120 		@see SoftConnectCaps()
       
  1121 
       
  1122 		@return KErrNone if UDC successfully connected, KErrGeneral if there was an error.
       
  1123 
       
  1124 		@publishedPartner @released
       
  1125 	*/
       
  1126 	virtual TInt UdcConnect() =0;
       
  1127 
       
  1128 	/** Disconnects the UDC	 - and thus the USB device - physically from the bus.
       
  1129 
       
  1130 		This might involve a call into the Variant DLL, as the mechanism to achieve the disconnection can be
       
  1131 		specific to the platform (rather than UDC specific). Since this functionality is not part of the USB
       
  1132 		specification it has to be explicitly supported, either by the UDC itself or by the hardware
       
  1133 		platform. If it is supported, then the member function SoftConnectCaps should be implemented to return
       
  1134 		ETrue.
       
  1135 
       
  1136 		@see SoftConnectCaps()
       
  1137 
       
  1138 		@return KErrNone if UDC successfully disconnected, KErrGeneral if there was an error.
       
  1139 
       
  1140 		@publishedPartner @released
       
  1141 	*/
       
  1142 	virtual TInt UdcDisconnect() =0;
       
  1143 
       
  1144 	/** Returns the USB cable connection status.
       
  1145 
       
  1146 		@return ETrue if the device is connected (via the USB cable) to a USB host, EFalse if not.
       
  1147 
       
  1148 		@publishedPartner @released
       
  1149 	*/
       
  1150 	virtual TBool UsbConnectionStatus() const  =0;
       
  1151 
       
  1152 	/** Returns a truth value showing if the VBUS line is powered or not.
       
  1153 
       
  1154 		Lack of power may indicate an unpowered host or upstream hub, or a disconnected cable.
       
  1155 
       
  1156 		@return ETrue if VBUS is powered, EFalse otherwise.
       
  1157 
       
  1158 		@publishedPartner @released
       
  1159 	*/
       
  1160 	virtual TBool UsbPowerStatus() const =0;
       
  1161 
       
  1162 	/** Returns the current power status of the USB device.
       
  1163 
       
  1164 		@return ETrue if the device is currently self-powered, EFalse if not.
       
  1165 
       
  1166 		@publishedPartner @released
       
  1167 	*/
       
  1168 	virtual TBool DeviceSelfPowered() const =0;
       
  1169 
       
  1170 	/** Returns a pointer to an array of TUsbcEndpointCaps structures, which describe the endpoint
       
  1171 		capabilities of this UDC.
       
  1172 
       
  1173 		The dimension of the array can be obtained by calling the member function DeviceTotalEndpoints().
       
  1174 		Note that there might be gaps in the array, as the endpoints are numbered using the 'real endpoint'
       
  1175 		numbering scheme. Here is how an array could look like:
       
  1176 
       
  1177 		@code
       
  1178 		static const TInt KUsbTotalEndpoints = 5;
       
  1179 		static const TUsbcEndpointCaps DeviceEndpoints[KUsbTotalEndpoints] =
       
  1180 		{
       
  1181 		//															 UDC #	  iEndpoints index
       
  1182 		{KEp0MaxPktSzMask,	(KUsbEpTypeControl	   | KUsbEpDirOut)}, //	 0 -  0
       
  1183 		{KEp0MaxPktSzMask,	(KUsbEpTypeControl	   | KUsbEpDirIn )}, //	 0 -  1
       
  1184 		{KUsbEpNotAvailable, KUsbEpNotAvailable},					 // --- Not present
       
  1185 		{KBlkMaxPktSzMask,	(KUsbEpTypeBulk		   | KUsbEpDirIn )}, //	 1 -  3
       
  1186 		{KBlkMaxPktSzMask,	(KUsbEpTypeBulk		   | KUsbEpDirOut)}	 //	 2 -  4
       
  1187 		};
       
  1188 		@endcode
       
  1189 
       
  1190 		For the endpoint max packet sizes on a USB 2.0 High-speed UDC, the PSL should provide
       
  1191 		the overlaid values for both FS and HS, as the PIL can deduce the appropriate values
       
  1192 		for either speed.
       
  1193 
       
  1194 		@see TUsbcEndpointCaps
       
  1195 		@see DeviceTotalEndpoints()
       
  1196 
       
  1197 		@return A pointer to an array of TUsbcEndpointCaps structures, which describe the endpoint
       
  1198 		capabilities of this UDC.
       
  1199 
       
  1200 		@publishedPartner @released
       
  1201 	*/
       
  1202 	virtual const TUsbcEndpointCaps* DeviceEndpointCaps() const =0;
       
  1203 
       
  1204 	/** Returns the number of elements in the array pointed to by the return value of DeviceEndpointCaps().
       
  1205 
       
  1206 		Note that this is not necessarily equal to the number of usable endpoints. In the example to the
       
  1207 		DeviceEndpointCaps() function, this value would be 5 even though there are only 4 endpoints.
       
  1208 
       
  1209 		@see DeviceEndpointCaps()
       
  1210 
       
  1211 		@return The number of elements in the array pointed to by the return value of DeviceEndpointCaps().
       
  1212 
       
  1213 		@publishedPartner @released
       
  1214 	*/
       
  1215 	virtual TInt DeviceTotalEndpoints() const =0;
       
  1216 
       
  1217 	/** Returns a truth value indicating whether or not this UDC or platform has the capability to disconnect
       
  1218 		and re-connect the USB D+ line under software control.
       
  1219 
       
  1220 		@see UdcConnect()
       
  1221 		@see UdcDisconnect()
       
  1222 
       
  1223 		@return ETrue if software connect/disconnect is supported, EFalse otherwise.
       
  1224 
       
  1225 		@publishedPartner @released
       
  1226 	*/
       
  1227 	virtual TBool SoftConnectCaps() const =0;
       
  1228 
       
  1229 	/** Returns a truth value indicating whether or not this UDC allows the accurate tracking of the USB
       
  1230 		device state.
       
  1231 
       
  1232 		This capability affects how device state change notifications to the LDD/user are being handled.
       
  1233 
       
  1234 		@return ETrue if this UDC allows the tracking of the USB device state, EFalse otherwise.
       
  1235 
       
  1236 		@publishedPartner @released
       
  1237 	*/
       
  1238 	virtual TBool DeviceStateChangeCaps() const =0;
       
  1239 
       
  1240 	/** Returns a truth value indicating whether the USB device controller (UDC) hardware supports
       
  1241 		detection of a plugged-in USB cable even when not powered.
       
  1242 
       
  1243 		This capability affects the power management strategy used by the USB Manager.
       
  1244 
       
  1245 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs.
       
  1246 		 The default implementation in the PIL returns EFalse.)
       
  1247 
       
  1248 		@return ETrue if this UDC supports USB cable detection when not powered, EFalse otherwise.
       
  1249 
       
  1250 		@publishedPartner @released
       
  1251 	*/
       
  1252 	virtual TBool CableDetectWithoutPowerCaps() const;
       
  1253 
       
  1254 	/** Returns a truth value indicating whether the USB device controller (UDC) hardware supports
       
  1255 		USB High-speed operation.
       
  1256 
       
  1257 		This capability affects driver functionality and behaviour throughout the implementation.
       
  1258 
       
  1259 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs.
       
  1260 		 The default implementation in the PIL returns EFalse.)
       
  1261 
       
  1262 		@return ETrue if this UDC supports USB High-speed operation, EFalse otherwise.
       
  1263 
       
  1264 		@publishedPartner @released
       
  1265 	*/
       
  1266 	virtual TBool DeviceHighSpeedCaps() const;
       
  1267 
       
  1268 	/** Returns a truth value indicating whether this PSL supports the new
       
  1269 		('V2') endpoint resource request scheme.
       
  1270 
       
  1271 		This capability can be queried from the user-side and may determine the
       
  1272 		way the USB application issues resource allocation requests.
       
  1273 
       
  1274 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs.
       
  1275 		 The default implementation in the PIL returns EFalse.)
       
  1276 
       
  1277 		@return ETrue if PSL supports the new endpoint resource request scheme,
       
  1278 		EFalse otherwise.
       
  1279 
       
  1280 		@publishedPartner @released
       
  1281 	*/
       
  1282 	virtual TBool DeviceResourceAllocV2Caps() const;
       
  1283 
       
  1284 	/** Returns a truth value indicating whether this UDC handles OTG HNP bus
       
  1285 		connects/disconnects automatically in hardware.
       
  1286 
       
  1287 		This capability will be queried by the PIL and determines the way the
       
  1288 		PIL calls the functions behind the
       
  1289 		iEnablePullUpOnDPlus / iDisablePullUpOnDPlus pointers.
       
  1290 
       
  1291 		If HNP is handled by hardware (TBool = ETrue) then the PIL will (in
       
  1292 		that order)
       
  1293 
       
  1294 		1) make calls to those function pointers dependent only on the
       
  1295 		readiness or otherwise of user-side USB Client support (i.e. the Client
       
  1296 		LDD calls DeviceConnectToHost() / DeviceDisconnectFromHost()), as
       
  1297 		opposed to also evaluating Client PDD EnableClientStack() /
       
  1298 		DisableClientStack() calls from the OTG driver.
       
  1299 
       
  1300 		2) delay its USB Reset processing incl. the notification of upper
       
  1301 		layers (LDD + user-side), plus the initial setting up of an Ep0 read
       
  1302 		until user-side USB Client support readiness has been signalled
       
  1303 		(i.e. until after a call to DeviceConnectToHost()).
       
  1304 
       
  1305 		(Function is not 'pure virtual' for backwards compatibility with
       
  1306 		 existing USB PSLs. The default implementation in the PIL returns EFalse.)
       
  1307 
       
  1308 		@return ETrue if UDC/PSL handles HNP connects/disconnects in hardware,
       
  1309 		EFalse otherwise.
       
  1310 
       
  1311 		@publishedPartner @released
       
  1312 	*/
       
  1313 	virtual TBool DeviceHnpHandledByHardwareCaps() const;
       
  1314 
       
  1315 	/** Implements anything the UDC (PSL) might require following bus Suspend signalling.
       
  1316 
       
  1317 		This function gets called by the PIL after it has been notified (by the PSL) about the Suspend
       
  1318 		condition.
       
  1319 
       
  1320 		@publishedPartner @released
       
  1321 	*/
       
  1322 	virtual void Suspend() =0;
       
  1323 
       
  1324 	/** Implements anything the UDC (PSL) might require following bus Resume signalling.
       
  1325 
       
  1326 		This function gets called by the PIL after it has been notified (by the PSL) about the Resume event.
       
  1327 
       
  1328 		@publishedPartner @released
       
  1329 	*/
       
  1330 	virtual void Resume() =0;
       
  1331 
       
  1332 	/** Implements anything the UDC (PSL) might require following bus Reset signalling.
       
  1333 
       
  1334 		This function gets called by the PIL after it has been notified (by the PSL) about the Reset event.
       
  1335 
       
  1336 		@publishedPartner @released
       
  1337 	*/
       
  1338 	virtual void Reset() =0;
       
  1339 
       
  1340 	/** Called by the PIL to signal to the PSL that it has finished processing a received Setup packet (on
       
  1341 		Ep0) and that the PSL can now prepare itself for the next Ep0 reception (for instance by re-enabling
       
  1342 		the Ep0 interrupt).
       
  1343 
       
  1344 		The reason for having this function is the situation where no Ep0 read has been set up by the user and
       
  1345 		thus a received Setup packet cannot immediately be delivered to the user. Once the user however sets
       
  1346 		up an Ep0 read, the PIL completes the request and eventually calls this function. This way we can
       
  1347 		implement some sort of flow-control.
       
  1348 
       
  1349 		@publishedPartner @released
       
  1350 	*/
       
  1351 	virtual void Ep0ReadSetupPktProceed() =0;
       
  1352 
       
  1353 	/** Called by the PIL to signal to the PSL that it has finished processing a received Ep0 data packet and
       
  1354 		that the PSL can now prepare itself for the next Ep0 reception (for instance by re-enabling the Ep0
       
  1355 		interrupt).
       
  1356 
       
  1357 		The reason for having this function is the situation where no Ep0 read has been set up by the user and
       
  1358 		thus a received packet cannot immediately be delivered to the user. Once the user however sets up an
       
  1359 		Ep0 read, the PIL completes the request and eventually calls this function. This way we can implement
       
  1360 		some sort of flow-control.
       
  1361 
       
  1362 		@publishedPartner @released
       
  1363 	*/
       
  1364 	virtual void Ep0ReceiveProceed() =0;
       
  1365 
       
  1366 	/** Returns a truth value indicating whether the USB controller hardware (UDC) supports being powered
       
  1367 		down while (a configuration is) active.
       
  1368 
       
  1369 		This capability affects the power management strategy used by the USB Manager.
       
  1370 
       
  1371 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs. The default
       
  1372 		implementation in the PIL - to be on the safe side - returns EFalse.)
       
  1373 
       
  1374 		@return ETrue if this UDC supports power-down while active, EFalse otherwise.
       
  1375 
       
  1376 		@publishedPartner @released
       
  1377 	*/
       
  1378 	virtual TBool PowerDownWhenActive() const;
       
  1379 
       
  1380 	/** Powers the UDC down, i.e. puts it into a (hardware-dependent) power-saving mode. Note that this
       
  1381 		function is not the same as StopUdc(). The difference is that while StopUdc() effectively turns the
       
  1382 		UDC off and so may invalidate all its settings, after a call to PowerDown() the UDC is expected to
       
  1383 		return to its previous state when PowerUp() is called. This function is also not the same as
       
  1384 		Suspend() which gets called by the PIL in response to a Suspend event on the bus, and only then
       
  1385 		(but apart from that the two functions are very similar).
       
  1386 
       
  1387 		This function won't be called by the PIL once the UDC is active if PowerDownWhenActive() returns
       
  1388 		EFalse (which it by default does).
       
  1389 
       
  1390 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs. The default
       
  1391 		implementation in the PIL does nothing.)
       
  1392 
       
  1393 		@see PowerUp()
       
  1394 		@see PowerDownWhenActive()
       
  1395 
       
  1396 		@return KErrNone if UDC was successfully powered down, KErrGeneral otherwise.
       
  1397 
       
  1398 		@publishedPartner @released
       
  1399 	*/
       
  1400 	virtual TInt PowerDown();
       
  1401 
       
  1402 	/** Powers the UDC up by exiting a (hardware-dependent) power-saving mode. Note that this function is not
       
  1403 		the same as StartUdc(). The difference is that while StartUdc() starts the UDC from zero and merely
       
  1404 		leads to the default state (i.e. not an active configuration), after a call to PowerUp() the UDC is
       
  1405 		expected to have returned to the state it was in before PowerDown() was called.
       
  1406 
       
  1407 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs. The default
       
  1408 		implementation in the PIL does nothing.)
       
  1409 
       
  1410 		@see PowerDown()
       
  1411 
       
  1412 		@return KErrNone if UDC was successfully powered up, KErrGeneral otherwise.
       
  1413 
       
  1414 		@publishedPartner @released
       
  1415 	*/
       
  1416 	virtual TInt PowerUp();
       
  1417 
       
  1418 	/** Puts the controller into a specific test mode (during HS operation only).
       
  1419 
       
  1420 		9.4.9 Set Feature: "The transition to test mode must be complete no later than 3 ms after the
       
  1421 		completion of the status stage of the request." (The status stage will have been completed
       
  1422 		immediately before this function gets called.)
       
  1423 
       
  1424 		(Function is not 'pure virtual' for backwards compatibility with existing USB PSLs.
       
  1425 		 The default implementation in the PIL returns KErrNotSupported.)
       
  1426 
       
  1427 		@param aTestSelector The specific test mode selector (@see usb.h).
       
  1428 
       
  1429 		@return KErrNone if the specified test mode was entered successfully,
       
  1430 		KErrGeneral otherwise.
       
  1431 
       
  1432 		@publishedPartner @released
       
  1433 	*/
       
  1434 	virtual TInt EnterTestMode(TInt aTestSelector);
       
  1435 
       
  1436 	/** Turn on USB client functionality in an OTG/Host setup.
       
  1437 
       
  1438 		This PSL function is called by the PIL when the OTG stack calls the PIL
       
  1439 		function EnableClientStack(). Immediately afterwards the PIL may
       
  1440 		connect the B-device to the bus (via the OTG stack). OtgEnableUdc() is
       
  1441 		called always after StartUdc().
       
  1442 
       
  1443 		There is no equivalent to this function in the non-OTG version of the
       
  1444 		USB PDD.
       
  1445 
       
  1446 		@return KErrNone if UDC successfully enabled, KErrGeneral otherwise.
       
  1447 
       
  1448 		@publishedPartner @released
       
  1449 	*/
       
  1450 	virtual TInt OtgEnableUdc();
       
  1451 
       
  1452 	/** Turn off USB client functionality in an OTG/Host setup.
       
  1453 
       
  1454 		This function is called by the PIL when the OTG stack calls the PIL
       
  1455 		function DisableClientStack(); the PIL will do this immediately after
       
  1456 		it has disconnected the B-device from the bus (via the OTG stack) and
       
  1457 		before calling StopUdc().
       
  1458 
       
  1459 		There is no equivalent to this function in the non-OTG version of the
       
  1460 		USB PDD.
       
  1461 
       
  1462 		@return KErrNone if UDC successfully disabled, KErrGeneral otherwise.
       
  1463 
       
  1464 		@publishedPartner @released
       
  1465 	*/
       
  1466 	virtual TInt OtgDisableUdc();
       
  1467 
       
  1468 private:
       
  1469 
       
  1470 	//
       
  1471 	// --- Private member functions (used by PIL) ---
       
  1472 	//
       
  1473 
       
  1474 	TInt DeRegisterClientCallback(const DBase* aClientId);
       
  1475 	TBool CheckEpAvailability(TInt aEndpointsUsed, const TUsbcEndpointInfoArray& aEndpointData, TInt aIfcNumber)
       
  1476 		const;
       
  1477 	TUsbcInterface* CreateInterface(const DBase* aClientId, TInt aIfc, TUint32 aFeatureWord);
       
  1478 	TInt CreateEndpoints(TUsbcInterface* aIfc, TInt aEndpointsUsed, const TUsbcEndpointInfoArray& aEndpointData,
       
  1479 						 TInt *aRealEpNumbers);
       
  1480 	TInt SetupIfcDescriptor(TUsbcInterface* aIfc, TUsbcClassInfo& aClass, DThread* aThread, TDesC8* aString,
       
  1481 							const TUsbcEndpointInfoArray& aEndpointData);
       
  1482 	TInt ClientId2InterfaceNumber(const DBase* aClientId) const;
       
  1483 	TUsbcInterfaceSet* ClientId2InterfacePointer(const DBase* aClientId) const;
       
  1484 	const DBase* InterfaceNumber2ClientId(TInt aIfcSet) const;
       
  1485 	TUsbcInterfaceSet* InterfaceNumber2InterfacePointer(TInt aIfcSet) const;
       
  1486 	inline const DBase* PEndpoint2ClientId(TInt aRealEndpoint) const;
       
  1487 	inline TInt PEndpoint2LEndpoint(TInt aRealEndpoint) const;
       
  1488 	TInt ActivateHardwareController();
       
  1489 	void DeActivateHardwareController();
       
  1490 	void DeleteInterfaceSet(TInt aIfcSet);
       
  1491 	void DeleteInterface(TInt aIfcSet, TInt aIfc);
       
  1492 	void CancelTransferRequests(TInt aRealEndpoint);
       
  1493 	void DeleteRequestCallback(const DBase* aClientId, TInt aEndpointNum, TTransferDirection aTransferDir);
       
  1494 	void DeleteRequestCallbacks(const DBase* aClientId);
       
  1495 	void StatusNotify(TUsbcDeviceState aState, const DBase* aClientId=NULL);
       
  1496 	void EpStatusNotify(TInt aRealEndpoint);
       
  1497 	void OtgFeaturesNotify();
       
  1498 	void RunClientCallbacks();
       
  1499 	void ProcessDataTransferDone(TUsbcRequestCallback& aRcb);
       
  1500 	void NextDeviceState(TUsbcDeviceState aNextState);
       
  1501 	TInt ProcessSuspendEvent();
       
  1502 	TInt ProcessSuspendEventProceed();
       
  1503 	TInt ProcessResumeEvent();
       
  1504 	TInt ProcessResetEvent(TBool aPslUpcall=ETrue);
       
  1505 	TInt ProcessCableInsertEvent();
       
  1506 	TInt ProcessCableRemoveEvent();
       
  1507 	TInt ProcessEp0ReceiveDone(TInt aCount);
       
  1508 	TInt ProcessEp0TransmitDone(TInt aCount, TInt aError);
       
  1509 	TInt ProcessEp0SetupReceived(TInt aCount);
       
  1510 	TInt ProcessEp0DataReceived(TInt aCount);
       
  1511 	TInt ProcessGetDeviceStatus(const TUsbcSetup& aPacket);
       
  1512 	TInt ProcessGetInterfaceStatus(const TUsbcSetup& aPacket);
       
  1513 	TInt ProcessGetEndpointStatus(const TUsbcSetup& aPacket);
       
  1514 	TInt ProcessSetClearDevFeature(const TUsbcSetup& aPacket);
       
  1515 	TInt ProcessSetClearIfcFeature(const TUsbcSetup& aPacket);
       
  1516 	TInt ProcessSetClearEpFeature(const TUsbcSetup& aPacket);
       
  1517 	TInt ProcessSetAddress(const TUsbcSetup& aPacket);
       
  1518 	TInt ProcessGetDescriptor(const TUsbcSetup& aPacket);
       
  1519 	TInt ProcessSetDescriptor(const TUsbcSetup& aPacket);
       
  1520 	TInt ProcessGetConfiguration(const TUsbcSetup& aPacket);
       
  1521 	TInt ProcessGetInterface(const TUsbcSetup& aPacket);
       
  1522 	TInt ProcessSetInterface(const TUsbcSetup& aPacket);
       
  1523 	TInt ProcessSynchFrame(const TUsbcSetup& aPacket);
       
  1524 	void ProceedSetDescriptor();
       
  1525 	void SetClearHaltFeature(TInt aRealEndpoint, TUint8 aRequest);
       
  1526 	TInt ClearHaltFeature(TInt aRealEndpoint);
       
  1527 	void ChangeConfiguration(TUint16 aValue);
       
  1528 	void InterfaceSetup(TUsbcInterface* aIfc);
       
  1529 	void InterfaceSetTeardown(TUsbcInterfaceSet* aIfc);
       
  1530 	void ChangeInterface(TUsbcInterface* aIfc);
       
  1531 	TInt DoForEveryEndpointInUse(TInt (DUsbClientController::*aFunction)(TInt), TInt& aCount);
       
  1532 	void EnterFullSpeed();
       
  1533 	void EnterHighSpeed();
       
  1534 	TInt EvaluateOtgConnectFlags();
       
  1535 	inline const TUsbcConfiguration* CurrentConfig() const;
       
  1536 	inline TUsbcConfiguration* CurrentConfig();
       
  1537 	inline TBool InterfaceExists(TInt aNumber) const;
       
  1538 	inline TBool EndpointExists(TUint aAddress) const;
       
  1539 	inline void Buffer2Setup(const TAny* aBuf, TUsbcSetup& aSetup) const;
       
  1540 	inline TUint EpIdx2Addr(TUint aRealEndpoint) const;
       
  1541 	inline TUint EpAddr2Idx(TUint aAddress) const;
       
  1542 	inline void SetEp0DataOutVars(const TUsbcSetup& aPacket, const DBase* aClientId = NULL);
       
  1543 	inline void ResetEp0DataOutVars();
       
  1544 	inline TBool IsInTheStatusList(const TUsbcStatusCallback& aCallback);
       
  1545 	inline TBool IsInTheEpStatusList(const TUsbcEndpointStatusCallback& aCallback);
       
  1546 	inline TBool IsInTheOtgFeatureList(const TUsbcOtgFeatureCallback& aCallback);
       
  1547 	inline TBool IsInTheRequestList(const TUsbcRequestCallback& aCallback);
       
  1548 	static void ReconnectTimerCallback(TAny* aPtr);
       
  1549 	static void CableStatusTimerCallback(TAny* aPtr);
       
  1550 	static void PowerUpDfc(TAny* aPtr);
       
  1551 	static void PowerDownDfc(TAny* aPtr);
       
  1552 
       
  1553 private:
       
  1554 
       
  1555 	//
       
  1556 	// --- Private data members ---
       
  1557 	//
       
  1558 
       
  1559 	static DUsbClientController* UsbClientController[KUsbcMaxUdcs];
       
  1560 
       
  1561 	TInt iDeviceTotalEndpoints;								// number of endpoints reported by PSL
       
  1562 	TInt iDeviceUsableEndpoints;							// number of endpoints reported to LDD
       
  1563 	TUsbcDeviceState iDeviceState;							// states as of USB spec chapter 9.1
       
  1564 	TUsbcDeviceState iDeviceStateB4Suspend;					// state before entering suspend state
       
  1565 	TBool iSelfPowered;										// true if device is capable of beeing self-powered
       
  1566 	TBool iRemoteWakeup;									// true if device is capable of signalling rmwakeup
       
  1567 	TBool iTrackDeviceState;								// true if we should track the device state in s/w
       
  1568 	TBool iHardwareActivated;								// true if controller silicon is in operating state
       
  1569 	TBool iOtgSupport;										// true if OTG is supported by this device
       
  1570 	TBool iOtgHnpHandledByHw;								// true if HNP dis/connect is handled by hardware
       
  1571 	TUint8 iOtgFuncMap;										// bitmap indicating OTG extension features
       
  1572 	TBool iHighSpeed;										// true if currently operating at high-speed
       
  1573 	TUsbcSetup iSetup;										// storage for a setup packet during its DATA_OUT
       
  1574 	TInt iEp0MaxPacketSize;									// currently configured max packet size for Ep0
       
  1575 	const DBase* iEp0ClientId;								// see comment at the begin of ps_usbc.cpp
       
  1576 	TUint16 iEp0DataReceived;								// indicates how many bytes have already been received
       
  1577 	TBool iEp0DataReceiving;								// true if ep0's in DATA_OUT stage
       
  1578 	TBool iEp0WritePending;									// true if a write on ep0 has been set up
       
  1579 	TBool iEp0ClientDataTransmitting;						// true if ep0's in DATA_IN on behalf of a client
       
  1580 	const DBase* iEp0DeviceControl;							// Device Ep0 requests are delivered to this LDD
       
  1581 	TUsbcDescriptorPool iDescriptors;						// the descriptors as of USB spec chapter 9.5
       
  1582 	TUint8 iCurrentConfig;									// bConfigurationValue of current Config (1-based!)
       
  1583 	RPointerArray<TUsbcConfiguration> iConfigs;				// the root of the modelled USB device
       
  1584 	TUsbcPhysicalEndpoint iRealEndpoints[KUsbcEpArraySize]; // array will be filled once at startup
       
  1585 	TUint8 iEp0_TxBuf[KUsbcBufSz_Ep0Tx];					// ep0 outgoing (tx) data is placed here
       
  1586 #ifdef USB_SUPPORTS_SET_DESCRIPTOR_REQUEST
       
  1587 	TUint8 iEp0_RxCollectionBuf[KUsbcBufSz_Ep0Rx];			// used for (optional) SET_DESCRIPTOR request
       
  1588 #endif
       
  1589 	TInt iEp0_RxExtraCount;									// number of bytes received but not yet delivered
       
  1590 	TBool iEp0_RxExtraData;									// true if iEp0_RxExtraCount is valid
       
  1591 	TInt iEp0_TxNonStdCount;								// number of bytes requested by non-std Ep0 request
       
  1592 	TUsbcRequestCallback* iRequestCallbacks[KUsbcEpArraySize]; // xfer requests; indexed by real ep number
       
  1593 	TSglQue<TUsbcRequestCallback> iEp0ReadRequestCallbacks;	// list of ep0 read requests
       
  1594 	TSglQue<TUsbcClientCallback> iClientCallbacks;          // registered LDD clients and their callback functions
       
  1595 	TSglQue<TUsbcStatusCallback> iStatusCallbacks;			// list of device state notification requests
       
  1596 	TSglQue<TUsbcEndpointStatusCallback> iEpStatusCallbacks; // list of endpoint state notification requests
       
  1597 	TSglQue<TUsbcOtgFeatureCallback> iOtgCallbacks;		    // list of OTG feature change requests
       
  1598 	NTimer iReconnectTimer;									// implements USB re-enumeration delay
       
  1599 	NTimer iCableStatusTimer;								// implements USB cable status detection delay
       
  1600 	DUsbcPowerHandler* iPowerHandler;						// pointer to USB power handler object
       
  1601 
       
  1602 protected:
       
  1603 	TDfc iPowerUpDfc;										// queued by power handler upon power-up
       
  1604 	TDfc iPowerDownDfc;										// queued by power handler upon power-down
       
  1605 
       
  1606 private:
       
  1607 	TBool iStandby;											// toggled by power handler as appropriate
       
  1608 	TBool iStackIsActive;									// client stack's function is usable
       
  1609 	TBool iOtgClientConnect;								// OTG stack wishes to connect to the host
       
  1610 	TBool iClientSupportReady;								// user-side USB Client support is loaded & active
       
  1611 	TBool iDPlusEnabled;									// set if both sides agree and DPLUS is asserted
       
  1612 	TBool iUsbResetDeferred;								// set when user-side wasn't ready yet
       
  1613 
       
  1614 public:
       
  1615 	TInt (*iEnablePullUpOnDPlus)(TAny* aOtgContext);		// these are to be filled in by the Host component
       
  1616 	TInt (*iDisablePullUpOnDPlus)(TAny* aOtgContext);		// in an OTG setup (otherwise unused)
       
  1617 	TAny* iOtgContext;										// to be passed into the above 2 functions
       
  1618 	};
       
  1619 
       
  1620 
       
  1621 /** Simple queue of status changes to be recorded.
       
  1622 	Items are fetched by userside when able.
       
  1623 */
       
  1624 class TUsbcDeviceStatusQueue
       
  1625 	{
       
  1626 public:
       
  1627 	TUsbcDeviceStatusQueue();
       
  1628 	void AddStatusToQueue(TUint32 aDeviceStatus);
       
  1629 	TInt GetDeviceQueuedStatus(TUint32& aDeviceStatus);
       
  1630 	void FlushQueue();
       
  1631 
       
  1632 private:
       
  1633 	TUint32 iDeviceStatusQueue[KUsbDeviceStatusQueueDepth];
       
  1634 	TInt iStatusQueueHead;
       
  1635 	};
       
  1636 
       
  1637 #include <drivers/usbcshared.inl>
       
  1638 
       
  1639 #endif	// __USBCSHARED_H__
       
  1640 
       
  1641 
       
  1642 
       
  1643 
       
  1644 
       
  1645 
       
  1646 
       
  1647 
       
  1648 
       
  1649 
       
  1650 
       
  1651 
       
  1652 
       
  1653 
       
  1654 
       
  1655 
       
  1656 
       
  1657