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\usbcsc.h

    15 // Kernel side definitions for the USB Device driver stack (PIL + LDD).

    16 // 

    17 //

    18 

    19 /**

    20  @file usbcsc.h

    21  @internalTechnology

    22 */

    23 

    24 #ifndef __USBCSC_H__

    25 #define __USBCSC_H__

    26 

    27 #include <kernel/kernel.h>

    28 #include <kernel/kern_priv.h>

    29 #include <kernel/kpower.h>

    30 #include <platform.h>

    31 

    32 #include <usb/d32usbcsc.h>

    33 

    34 // #include <drivers/usbcshared.h>

    35 #include <usb/usbcshared.h>

    36 

    37 /** LDD Major version, This should agree with the information in RDevUsbcClient::TVer.

    38 */

    39 const TInt KUsbcScMajorVersion = 0;

    40 

    41 /** LDD Minor version, This should agree with the information in RDevUsbcClient::TVer.

    42 */

    43 const TInt KUsbcScMinorVersion = 1;

    44 

    45 /** LDD Build version, This should agree with the information in RDevUsbcClient::TVer.

    46 */

    47 const TInt KUsbcScBuildVersion = KE32BuildVersionNumber;

    48 

    49 /** Must correspond to the max enum of TRequest + 1;

    50     currently this is ERequestOtgFeaturesNotify = 10.

    51 */

    52 const TInt KUsbcScMaxRequests = 11;

    53 

    54 // Request queue sizes need to be power of 2.

    55 

    56 /** The number of requests that can be queued on any IN endpoint */

    57 const TInt KUsbcScInRequests = 4;

    58 /** The number of requests that can be queued on any OUT endpoint */

    59 const TInt KUsbcScOutRequests = 2;

    60 

    61 /** In TUsbcScBuffer.iDirection, this indicates that the endpoint is an IN endpoint */

    62 const TInt KUsbcScIn =  0;

    63 /** In TUsbcScBuffer.iDirection, this indicates that the endpoint is an OUT endpoint */

    64 const TInt KUsbcScOut = 1;

    65 

    66 

    67 /** In TUsbcScBuffer.iDirection, this indicates that the endpoint is an Bidirectional endpoint

    68 currently operating as an IN endpoint */

    69 const TInt KUsbcScBiIn = 2;

    70 /** In TUsbcScBuffer.iDirection, this indicates that the endpoint is an Bidirectional endpoint

    71 currently operating as an OUT endpoint */

    72 const TInt KUsbcScBiOut = 3;

    73 

    74 /** The number of directions supported for endpoints, other then EP0.  Currently 2, IN and OUT. */

    75 const TInt KUsbcScDirections = 2;

    76 

    77 /** In TUsbcScBuffer::iDirection, this indicates that the endpoint direction is Unknown. */

    78 const TInt KUsbcScUnknown = 4;

    79 

    80 const TInt KPageSize = 0x1000;

    81 

    82 /** The default buffer size requested for a endpoint, if the user app does not specify a size.*/

    83 const TInt KUsbcScDefaultBufferSize = 0x10000; // 64k

    84 

    85 /** The size of the unmapped region of memory between endpoint buffers.

    86 This serves as a guard region, making memory over/under runs more obviose.*/

    87 const TInt KGuardSize = KPageSize;

    88 

    89 /** The size put aside for the chunk header structre.*/

    90 const TInt KHeaderSize = KPageSize;

    91 

    92 /** For buffers of size >= KUsbScBigBuffIs, The smallest unit of continiouse memory that will be used.

    93 No read will be set up smaller then this, to avoid overly fragmenting the data.

    94 */

    95 const TInt KUsbSc_BigBuff_MinimumRamRun = KPageSize;

    96 

    97 /** For buffers of size < KUsbScBigBuffIs, The smallest unit of continiouse memory that will be used.

    98 No read will be set up smaller then this, to avoid overly fragmenting the data.*/

    99 const TInt KUsbSc_SmallBuff_MinimumRamRun = 1024;

   100 

   101 /** The size a buffer request has to be to switch to using KUsbSc_BigBuff_MinimumRamRun.

   102 If the requested buffer is smaller, then the smallest memory allocated to a buffer is KPageSize*/

   103 const TInt KUsbScBigBuffIs = KPageSize*6;

   104 

   105 

   106 

   107 // EP0 is mapped manually, unlike the other endpoints.

   108 

   109 /** The position, within the chunk, that the EP0 IN buffer appears*/

   110 const TInt KUsbScEP0InBufPos = 0x800;

   111 /** The position, within the chunk, that the EP0 IN buffer ends*/

   112 const TInt KUsbScEP0InBufEnd = KUsbScEP0InBufPos + 0x400;

   113 

   114 // Its better for Out to go 2nd, so gaurd page after it.

   115 /** The position, within the chunk, that the EP0 OUT buffer appears*/

   116 const TInt KUsbScEP0OutBufPos = 0xc00;

   117 /** The position, within the chunk, that the EP0 OUT buffer ends*/

   118 const TInt KUsbScEP0OutBufEnd = KUsbScEP0OutBufPos + 0x400;

   119 

   120 /** The number of the entry within the chunk BufferRecord table, for the OUT ep0 buffer.*/

   121 const TInt KUsbcScEp0OutBuff = 0;

   122 /** The number of the entry within the chunk BufferRecord table, for the IN ep0 buffer.*/

   123 const TInt KUsbcScEp0InBuff = 1;

   124 

   125 

   126 //

   127 //########################### Logical Device Driver (LDD) #############################

   128 //

   129 

   130 /** USB LDD factory class.

   131 */

   132 class DUsbcScLogDevice : public DLogicalDevice

   133     {

   134 public:

   135     DUsbcScLogDevice();

   136     virtual TInt Install();

   137     virtual void GetCaps(TDes8& aDes) const;

   138     virtual TInt Create(DLogicalChannelBase*& aChannel);

   139     };

   140 

   141 

   142 class DLddUsbcScChannel;

   143 class TUsbcScBuffer;

   144 /** Endpoint tracking for the LDD buffering etc.

   145 */

   146 class TUsbcScEndpoint

   147     {

   148 public:

   149     TUsbcScEndpoint(DLddUsbcScChannel* aLDD, DUsbClientController* aController,

   150                   const TUsbcScEndpointInfo* aEndpointInfo, TInt aEndpointNum

   151                   );

   152     ~TUsbcScEndpoint();

   153     TInt Construct();

   154     void CancelTransfer(DThread* aThread);

   155     void AbortTransfer();

   156     inline TUsbcScEndpointInfo* EndpointInfo();

   157     inline TInt RxBytesAvailable() const;

   158     inline void ResetTransferInfo();

   159     inline void SetClientReadPending(TBool aVal);

   160     inline void SetClientWritePending(TBool aVal);

   161     inline TBool ClientWritePending();

   162     inline TBool ClientReadPending();

   163     inline void SetRealEpNumber(TInt aRealEpNumber);

   164     inline TInt RealEpNumber() const;

   165     inline TInt EpNumber() const;

   166     inline void StartBuffer();

   167     inline void SetBuffer(TUsbcScBuffer* aBuffer);

   168     inline TUsbcScBuffer* GetBuffer();

   169 

   170 

   171 private:

   172     static void RequestCallback(TAny* aTUsbcScEndpoint);

   173     void TxComplete();

   174     TInt RxComplete(TBool aReEntrant);

   175     void RxCompleteNow();

   176 

   177 

   178 

   179 public:

   180     TUsbcRequestCallback* iRequestCallbackInfo;

   181 

   182 private:

   183     DUsbClientController* iController;

   184     TUsbcScEndpointInfo iEndpointInfo;

   185     TBool iClientReadPending;

   186     TBool iClientWritePending;

   187     TInt iEndpointNumber;

   188     TInt iRealEpNumber;

   189     DLddUsbcScChannel* iLdd;

   190     TInt iError;

   191     TUint32 iBytesTransferred;

   192     TInt iBandwidthPriority;

   193     TUsbcScBuffer* iBuffer;

   194 

   195     };

   196 

   197 

   198 /** Linked list of 'alternate setting' info for use by the LDD.

   199 */

   200 class TUsbcScAlternateSetting

   201     {

   202 public:

   203     TUsbcScAlternateSetting();

   204     ~TUsbcScAlternateSetting();

   205 

   206 public:

   207     TUsbcScAlternateSetting* iNext;

   208     TUsbcScAlternateSetting* iPrevious;

   209     TInt iNumberOfEndpoints;

   210     TUint iSetting;

   211     TUsbcScEndpoint* iEndpoint[KMaxEndpointsPerClient + 1];

   212     };

   213 

   214 class TUsbcScAlternateSettingList

   215     {

   216 public:

   217     TUsbcScAlternateSettingList();

   218     ~TUsbcScAlternateSettingList();

   219 

   220 public:

   221     TUsbcScAlternateSetting* iHead;

   222     TUsbcScAlternateSetting* iTail;

   223     };

   224 

   225 class TUsbcScChunkInfo

   226     {

   227 public:

   228     TUsbcScChunkInfo(DLogicalDevice* aLdd);

   229     TInt CreateChunk(TInt aTotalSize);

   230     void Close();

   231     TInt ChunkAlloc(TInt aOffset, TInt aSize);

   232     void ChunkCleanup();

   233     TInt GetPhysical(TInt aOffset, TPhysAddr* aPhysical);

   234     static TInt New(TUsbcScChunkInfo*& aChunk, TInt aSize, DLogicalDevice* aLdd);

   235 private:

   236     TUint* iPhysicalMap;

   237 public:

   238     DChunk* iChunk;

   239     TDfc iCleanup;

   240 

   241     TInt8 iPageNtz; // Number of trailing zeros for a page. (Eg 4k page has 12 t.z.)

   242     TInt iAllocatedSize;

   243     TInt8* iChunkMem;

   244     TUint32 iChunkMapAttr;

   245     DLogicalDevice* iLdd;

   246     };

   247 

   248 

   249 // Used to represent a matrix of endpoints with a column of sizes.

   250 // Used by TRealizeInfo

   251 

   252 class TEndpointSortBufs

   253     {

   254     public:

   255         TUsbcScEndpoint** iEp;

   256         TInt* iSizes;

   257         TInt iEps;

   258     };

   259 

   260 // This is used to calculate the layout of the shared chunk

   261 // based on a list of alternative settings / endpoints provided.

   262  

   263 class TRealizeInfo

   264     {

   265     public:

   266         void Init(TUsbcScAlternateSettingList* aAlternateSettingList);

   267         TInt CopyAndSortEndpoints();

   268         void CalcBuffSizes();

   269         void Free();

   270 

   271         void LayoutChunkHeader(TUsbcScChunkInfo* aChunkInfo);

   272     public:

   273         TInt iMaxEndpoints;

   274         TInt iTotalSize;

   275         TInt iTotalBuffers;

   276         TInt iAltSettings;

   277         TEndpointSortBufs iBufs[KUsbcScDirections];

   278         TUsbcScAlternateSettingList* iAlternateSettingList;

   279 

   280         // Chunk layout info.

   281         TUsbcScChunkBuffersHeader* iChunkStuct;

   282         TUsbcScChunkAltSettingHeader* iAltSettingsTbl;

   283     };

   284 

   285 

   286 

   287 /** The channel class - the actual USB LDD.

   288 */

   289 class DLddUsbcScChannel : public DLogicalChannel

   290     {

   291 public:

   292     DLddUsbcScChannel();

   293     ~DLddUsbcScChannel();

   294     virtual void HandleMsg(TMessageBase* aMsg);

   295     virtual TInt DoCreate(TInt aUnit, const TDesC8* aInfo, const TVersion& aVer);

   296     virtual TInt RequestUserHandle(DThread* aThread, TOwnerType aType);

   297     inline DThread* Client() const {return iClient;}

   298     inline TBool ChannelClosing() const {return iChannelClosing;}

   299     inline TUint AlternateSetting() const {return iAlternateSetting;}

   300     

   301     static void RequestCallbackEp0(TAny* aTUsbcScChannel);

   302 

   303 private:

   304 

   305     TInt DoCancel(TInt aReqNo, TUint aMask, TUint a1);

   306     TInt DoRequest(TInt aReqNo, TRequestStatus* aStatus, TAny* a1, TAny* a2);

   307     TInt DoControl(TInt aFunction, TAny* a1, TAny* a2);

   308     TInt DoReadDataNotify(TRequestStatus* aStatus, TInt aBufferNum, TInt aLength);

   309     void StartDataRead(TInt aBufferNum);

   310     TInt DoWriteData(TRequestStatus* aStatus,TInt aBufferNum, TUint aStart, TUint aLength, TUint aFlags);

   311     TBool AlternateDeviceStateTestComplete();

   312     TInt SetInterface(TInt aInterfaceNum, TUsbcScIfcInfo* aUserInterfaceInfoBuf);

   313     void StartEpReads();

   314     void DestroyAllInterfaces();

   315     void DestroyInterface(TUint aInterface);

   316     void DestroyEp0();

   317     inline TBool ValidEndpoint(TInt aEndpoint);

   318     TInt GetRealEpForEpResource(TInt aEndpoint, TInt& aRealEp);

   319     inline TBool Configured();

   320     TInt DoEmergencyComplete();

   321     void ReadDes8(const TAny* aPtr, TDes8& aDes);

   322     TInt SetupEp0();

   323     void CancelNotifyEndpointStatus();

   324     void CancelNotifyOtgFeatures();

   325     static void StatusChangeCallback(TAny* aDLddUsbcChannel);

   326     static void EndpointStatusChangeCallback(TAny* aDLddUsbcChannel);

   327     static void OtgFeatureChangeCallback(TAny* aDLddUsbcChannel);

   328     static void EmergencyCompleteDfc(TAny* aDLddUsbcChannel);

   329     void DeConfigure(TInt aErrorCode);

   330     TInt SelectAlternateSetting(TUint aAlternateSetting);

   331     TInt EpFromAlternateSetting(TUint aAlternateSetting, TInt aEndpoint);

   332     TInt ProcessAlternateSetting(TUint aAlternateSetting);

   333     TInt32 StartNextInAlternateSetting();

   334     TInt ProcessDeviceState(TUsbcDeviceState aDeviceState);

   335     void ResetInterface(TInt aErrorCode);

   336     void PanicClientThread(TInt aReason);

   337 

   338     TInt RealizeInterface(void);

   339 

   340 private:

   341     DUsbClientController* iController;

   342     DThread* iClient;

   343     TBool iValidInterface;

   344     

   345     TUsbcScAlternateSettingList* iAlternateSettingList;

   346     TUsbcScEndpoint** iEndpoint;  // Pointer to the current endpoint set.

   347 

   348     static const TInt KUsbcMaxRequests = RDevUsbcScClient::ERequestMaxRequests;

   349     TRequestStatus* iRequestStatus[KUsbcMaxRequests];

   350     TUsbcClientCallback iCompleteAllCallbackInfo;

   351     TAny* iStatusChangePtr;

   352     TUsbcStatusCallback iStatusCallbackInfo;

   353     TAny* iEndpointStatusChangePtr;

   354     TUsbcEndpointStatusCallback iEndpointStatusCallbackInfo;

   355     TAny* iOtgFeatureChangePtr;

   356     TUsbcOtgFeatureCallback iOtgFeatureCallbackInfo;

   357     TUint8* iBufferBaseEp0;

   358     TInt iBufferSizeEp0;

   359     TInt iNumberOfEndpoints;

   360     TUsbcDeviceState iDeviceState;

   361     TUsbcDeviceState iOldDeviceState;

   362     TBool iOwnsDeviceControl;

   363     TUint16 iAlternateSetting;

   364     TUint16 iAsSeq;

   365 

   366     TUsbcDeviceStatusQueue* iStatusFifo;

   367     TBool iUserKnowsAltSetting;

   368     TBool iDeviceStatusNeeded;

   369     TBool iChannelClosing;

   370     TBool iRealizeCalled;

   371 

   372     TUsbcScChunkInfo* iChunkInfo;

   373     TInt iNumBuffers;

   374     TUsbcScBuffer *iBuffers;

   375 

   376     TUsbcScEndpoint* iEp0Endpoint;

   377     TInt iEP0InBuff;

   378     TInt iEP0OutBuff;

   379 

   380     friend class TUsbcScBuffer;

   381     friend void TUsbcScEndpoint::AbortTransfer();

   382     };

   383 

   384 /**

   385 This class is used by TUsbcScStatusList to form a queue of status requests.

   386 These requests are on a buffer basis, so that all buffers can have at least two requests

   387 pending, at the same time. (i.e. buffer 1 could have two requests outstanding, as well as 2 on buffer 2.)

   388 */

   389 

   390 class TUsbcScStatusElement

   391 {

   392 public:

   393     TRequestStatus* iStatus;

   394     TInt iLength;

   395     TUint iStart;

   396     TUint iFlags;    

   397 };

   398 

   399 enum TUsbcScStatusState

   400 {

   401     ENotRunning,

   402     EInProgress,

   403     EReadingAhead,

   404     EFramgementInProgress

   405 };

   406 

   407 class TUsbcScStatusList

   408 {

   409 public:

   410     TInt Construct(TInt aSize, DThread* aThread);

   411     void Destroy();

   412 

   413     TUsbcScStatusElement* Next();

   414     void Pop();

   415     TInt Add(TRequestStatus* aStatus, TInt aLength, TUint aStart, TUint aFlags);

   416     void CancelQueued(TInt aErrorCode=KErrCancel);

   417     TInt Complete(TInt aError);

   418     void Complete();

   419 public:

   420     TUsbcScStatusState iState;

   421 

   422 private:

   423     DThread* iClient;

   424     TInt iHead;   // The element at the head of the queue, ie, the earliest added, and next to be removed.

   425     TInt iLength; // Length of queue, ie number of elements within

   426     TInt iSize;   // size of array, ie, max # of requests at a time.

   427     TUsbcScStatusElement* iElements;

   428 

   429 };

   430 

   431 

   432 

   433 /**

   434 This class holds the kernel's copy of all the details related to a shared endpoint buffer,

   435 and provides methods for the LDD to manipulate it.

   436 */

   437 class TUsbcScBuffer

   438 {

   439 public:

   440     static const TInt8 KNoEpAssigned=0;

   441     static const TInt8 KEpIsEnding=1;

   442     static const TInt8 KEpIsStarting=2;

   443 

   444 public:

   445     TInt Construct(TInt aDirection, DLddUsbcScChannel* aLdd, TInt aBufferOffset, TInt aBufferEndOffset, TInt aMinReadSize, TInt aMaxPacketSize, TInt aMaxReadSize);

   446     void CreateChunkBufferHeader();

   447     void StartEndpoint(TUsbcRequestCallback* iRequestInfo, TUint iFlags);

   448 

   449     void Destroy();

   450 

   451     TInt StartDataRead();

   452     void CompleteRead(TBool aStartNextRead=ETrue);

   453     void PopStall();

   454     void StartDataWrite();

   455     void CompleteWrite();

   456     void Cancel(TInt aErrorCode);

   457 

   458     void UpdateBufferList(TInt aByteCount,TUint aFlags, TBool aStartNextRead=ETrue);

   459     void Ep0CancelLddRead();

   460     void SendEp0StatusPacket(TInt aState);

   461 

   462 public:

   463     

   464     TInt8 iDirection;

   465     TInt8 iMode;

   466     TInt8 iNeedsPacket;

   467     TInt8 iReserved;

   468     DLddUsbcScChannel* iLdd;

   469     TLinAddr iChunkAddr;

   470     SUsbcScBufferHeader* iBufferStart;

   471     TUint iBufferEnd; // One word on from the last word in the buffer.

   472     TUint iAlignMask;

   473     TUsbcScStatusList iStatusList;

   474     TUsbcRequestCallback* iCallback;

   475     union 

   476     {

   477         TInt iHead; // Out endpoints only;

   478         TUint iSent; // In endpoints only

   479     };

   480     TUsbcScChunkInfo* iChunkInfo;

   481     TInt iMinReadSize;

   482     TInt iMaxReadSize;

   483     TInt iMaxPacketSize;  // 0 indicates unconfiured.

   484     TInt iFirstPacket;

   485     TInt iStalled;

   486 

   487     // needed for backwards compatibility

   488     TUsbcPacketArray iIndexArray[KUsbcDmaBufNumMax]; // Has 2 elements

   489     TUsbcPacketArray iSizeArray[KUsbcDmaBufNumMax];  // Has 2 elements

   490 #ifdef _DEBUG

   491     TUint iSequence;

   492 #endif

   493 

   494 };

   495 

   496 

   497 

   498 #include <usb/usbcsc.inl>

   499 

   500 #endif    // __USBCSC_H__