1 // Copyright (c) 2008-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\d32usbcsc.h

    15 // User side class definitions for USB Device support.

    16 // 

    17 //

    18 

    19 /**

    20  @file d32usbcsc.h

    21  @publishedPartner

    22  @released

    23 */

    24 

    25 #ifndef __D32USBCSC_H__

    26 #define __D32USBCSC_H__

    27 

    28 #include <e32ver.h>

    29 #include <usb/usb.h>

    30 #include <usb/d32usbcshared.h>

    31 

    32 

    33 /** This means that SetInterface was called after RealizeInterface had been called.

    34     RealizeInterface is meant to signal that all interfaces have been set.

    35 */

    36 const TInt KErrUsbAlreadyRealized = -6813; //Changed from -6713 for future compatibility with the d32usbcshared.h file

    37 

    38 const TInt KErrAlternateSettingChanged = -6814;

    39 

    40 

    41 const TUint KChunkCellSize = 1; //1 32 bit integer

    42 const TInt KEpDescPacketSizeOffset = 4;

    43 

    44 /** The user side enpoint number of Endpoint Zero. */

    45 const TInt KEp0Number = 0;

    46 

    47 /* Used in TUsbcScHdrEndpointRecord to describe the endpoint type

    48 */

    49 

    50 const TUint8 KUsbScHdrEpDirectionIn=1;

    51 const TUint8 KUsbScHdrEpDirectionOut=2;

    52 const TUint8 KUsbScHdrEpDirectionBiDir=3;

    53 

    54 

    55 const TUint8 KUsbScHdrEpTypeControl = 0;

    56 const TUint8 KUsbScHdrEpTypeIsochronous =1;

    57 const TUint8 KUsbScHdrEpTypeBulk = 2;

    58 const TUint8 KUsbScHdrEpTypeInterrupt = 3;

    59 const TUint8 KUsbScHdrEpTypeUnknown = ~0;

    60 /** Used in the the Shared Chunk Header, to represent an endpoint.

    61 */

    62 class TUsbcScHdrEndpointRecord

    63     {

    64 public:

    65     inline TUsbcScHdrEndpointRecord(TInt aBufferNo, TUint8 aType);

    66     inline TUint Direction() const;

    67     inline TUint Type() const;

    68 public:

    69     TUint8 iBufferNo;

    70     TUint8 iType;

    71     TUint16 iReserved;

    72     };

    73 

    74 

    75 // This is used to hold the geometry of the shared buffers

    76 class TUsbcScBufferRecord

    77     {

    78     friend class DLddUsbcScChannel;

    79 

    80 public:

    81     inline TUint Offset() const;

    82     inline TUint Size() const;

    83 private:

    84     inline void Set(TUint aOffset, TUint aEndOffset);

    85     TUint iOffset;

    86     TUint iSize;

    87     };

    88 

    89 struct SUsbcScBufferHeader

    90     {

    91     TInt iHead;        // Where the LDD will next write a transfer

    92     TInt iTail;        // Indicates the fist packet that user side is processing (anything prior is disposable)

    93     TInt iBilTail;  // This is not used by LDD at all, but just for the BIL's benifit.

    94     };

    95 

    96 

    97 struct SUsbcScAlternateSetting

    98     {

    99     TUint16 iSetting;

   100     TUint16 iSequence;

   101     };

   102 

   103 /** Endpoint pair information.  This can be used to control pairing of endpoint

   104 for classes that require explicit pairing of endpoint, such as ADC.

   105 

   106 This is currently not used.

   107 */

   108 

   109 class TEndpointPairInfo

   110 {

   111 public:

   112     TEndpointPairInfo(TUint8 aType=0, TUint16 aPair=0, TUint8 aSpare=0);

   113 public:

   114     TUint8 iType;

   115     TUint8 iSpare;

   116     TUint16 iPair;

   117 }; 

   118 

   119 /**

   120 This is the buffer number reserved for use with endpoint zero with the  ReadDataNotify and WriteData methods.

   121 */

   122 const TInt KUsbcScEndpointZero = -1;

   123 

   124 /**

   125 This flag is reserved in TUsbcscEndpointInfo::iFlags, to indicate that the client driver's client wishes reads to operate in a coupled fashion.

   126 This behaviour is not currently supported.

   127 */

   128 const TUint KUsbScCoupledRead = 0x1;

   129 

   130 /**

   131 This flag, used in parameter aFlag of WriteData, is used to indicate that a ZLP should be sent.

   132 */

   133 const TUint KUsbcScWriteFlagsZlp = 0x0001;

   134 

   135 

   136 // Bit fields used in iFlags of TUsbcScTransferHeader

   137 

   138 const TUint KUsbcScShortPacket = 0x0001;

   139 const TUint KUsbcScStateChange = 0x0004;

   140 

   141 class TUsbcScTransferHeader

   142 {

   143 public:

   144 #ifdef _DEBUG

   145     TUint iHashId;

   146     TUint iSequence;

   147 #endif

   148     TUint iBytes;

   149     TUint iFlags;

   150     TUint iNext;

   151     TUint16 iAltSettingSeq;

   152     TInt16 iAltSetting;

   153     union

   154     {

   155         TUint  i[1]; // Extends

   156         TUint8 b[4]; // Extends

   157     } iData;

   158 };

   159 

   160 /** The desired endpoint capabilities used in RDevUsbcScClient::SetInterface().

   161 

   162 This derived class has additional fields used in the shared chunk USB driver.

   163 */

   164 class TUsbcScEndpointInfo: public TUsbcEndpointInfo

   165     {

   166 public:

   167     TUsbcScEndpointInfo(TUint aType=UsbShai::KUsbEpTypeBulk, TUint aDir=UsbShai::KUsbEpDirOut, TInt aInterval=0, TInt aExtra=0,

   168                                                 TUint aBufferSize=0, TUint aReadSize=0);

   169 

   170 

   171 public:

   172     /** This indicates the requested size of the endpoint buffer and must be at

   173         least as large as iReadSize.

   174     */

   175     TUint iBufferSize;

   176 

   177     /** This is the amount of data that the LDD reads from the bus before it sets

   178         up another read and is normally intended to read many packets.

   179     */

   180     TUint iReadSize;

   181 

   182     /** TEndpointPairInfo represents pairing information for isochronous endpoints.

   183         Should be zero in other cases.  If this specifies paired endpoints then

   184         iExtra (in the base class TUsbcEndpointInfo) also needs to be set to the

   185         class specific size for this endpoint descriptor (This is here only for future use).

   186     */

   187     TEndpointPairInfo iPairing;

   188     

   189     /** The necessary alignment, in bytes, that needs to be applied to the transfer start points

   190         of the data.  This is only observed on OUT endpoints.  Zero can be specified to indicate

   191         there are no class side requirements for alignment.   The alignment for OUT endpoints is

   192         which ever is greater of this field or the USB hardware requirements.

   193     */

   194     TUint iAlignment;

   195 

   196     /** Flags to indicate how the endpoint should function. None currently defined,

   197         but could be used to allow support for direct read.

   198     */

   199     TUint iFlags;

   200     

   201     /** Reserved for future use. */

   202     TUint32 iReserved2[2];

   203     };

   204 

   205 /** This must be filled in prior to a call to RDevUsbcClient::SetInterface().

   206 */

   207 class TUsbcScInterfaceInfo

   208     {

   209 public:

   210     TUsbcScInterfaceInfo(TInt aClass=0, TInt aSubClass=0, TInt aProtocol=0,

   211                        TDesC16* aString=NULL, TUint aTotalEndpoints=0);

   212 public:

   213     /** The class, subclass and protocol that this interface supports. */

   214     TUsbcClassInfo iClass;

   215     /** The description string for the interface. Used to construct the interface string descriptor. */

   216     const TDesC16* iString;

   217     /** Total number of endpoints being requested (0-5). Endpoint 0 should not be included in this number. */

   218     TUint iTotalEndpointsUsed;

   219     /** Desired properties of the endpoints requested.

   220         Do NOT include endpoint 0.

   221         APIs use endpoint numbers that are offsets into this array.

   222     */

   223     TUsbcScEndpointInfo iEndpointData[KMaxEndpointsPerClient];

   224     /** 32 flag bits used for specifying miscellaneous Interface features.

   225         Currently defined are:

   226         - KUsbcInterfaceInfo_NoEp0RequestsPlease = 0x00000001

   227     */

   228     TUint32 iFeatureWord;

   229     };

   230 

   231 /** Package buffer for a TUsbcInterfaceInfo object.

   232 

   233     @see TUsbcInterfaceInfo

   234 */

   235 typedef TPckgBuf<TUsbcScInterfaceInfo> TUsbcScInterfaceInfoBuf;

   236 

   237 struct TUsbcScChunkHdrOffs

   238     {

   239     TUint iBuffers;

   240     TUint iAltSettings;

   241     };

   242 

   243 

   244 class TUsbcScChunkBuffersHeader  // Not instantiable

   245     {

   246     friend class DLddUsbcScChannel;

   247     friend class TRealizeInfo;

   248 

   249 public:

   250     inline TUsbcScBufferRecord* Ep0Out() const;

   251     inline TUsbcScBufferRecord* Ep0In() const;

   252     inline TUsbcScBufferRecord* Buffers(TInt aBuffer) const;

   253     inline TInt NumberOfBuffers() const;

   254 

   255 private:

   256     TUsbcScChunkBuffersHeader();

   257 private:

   258     TInt iRecordSize;

   259     TInt  iNumOfBufs;

   260     TUint8 iBufferOffset[8]; // Extends

   261     };

   262 

   263 struct TUsbcScChunkAltSettingHeader // Not instantiable

   264     {

   265     TInt iEpRecordSize;

   266     TInt iNumOfAltSettings;

   267     TUint iAltTableOffset[1]; // Extends

   268     };

   269 

   270 class TEndpointBuffer;

   271 

   272 

   273 /** The user side handle to the USB client driver.

   274 */

   275 class RDevUsbcScClient : public RBusLogicalChannel

   276     {

   277 public:

   278     /** @internalComponent */

   279     enum TVer

   280         {

   281         EMajorVersionNumber = 0,

   282         EMinorVersionNumber = 1,

   283         EBuildVersionNumber = KE32BuildVersionNumber

   284         };

   285 

   286 // Bit pattern. s = Request/Control.  c = Cancel,  m = mode bits, B = Buffer number, R = request number.

   287 //    scmm mmmm |  mmmm mmmm | mmBB BBBB |RRRR RRRR  

   288 

   289     enum TRequest

   290         {

   291         ERequestWriteData = 1,

   292         ERequestReadDataNotify = 2,     

   293         ERequestAlternateDeviceStatusNotify = 3,

   294         ERequestReEnumerate = 4,

   295         ERequestEndpointStatusNotify = 5,

   296          ERequestOtgFeaturesNotify = 6,

   297         ERequestMaxRequests, // 7

   298 

   299         ERequestCancel = 0x40000000,

   300 

   301         ERequestWriteDataCancel                        = ERequestWriteData                   | ERequestCancel,

   302         ERequestReadDataNotifyCancel                = ERequestReadDataNotify              | ERequestCancel,

   303         ERequestAlternateDeviceStatusNotifyCancel     = ERequestAlternateDeviceStatusNotify | ERequestCancel,

   304         ERequestReEnumerateCancel                     = ERequestReEnumerate                 | ERequestCancel,

   305         ERequestEndpointStatusNotifyCancel             = ERequestEndpointStatusNotify        | ERequestCancel,

   306         ERequestOtgFeaturesNotifyCancel             = ERequestOtgFeaturesNotify           | ERequestCancel

   307         };

   308 

   309     enum TControl

   310         {

   311         // Changing the order of these enums will break BC.

   312         EControlEndpointZeroRequestError,                    // 00

   313         EControlEndpointCaps,

   314         EControlDeviceCaps,

   315         EControlGetAlternateSetting,

   316         EControlDeviceStatus,

   317         EControlEndpointStatus,

   318         EControlSetInterface,

   319         EControlReleaseInterface,

   320         EControlSendEp0StatusPacket,

   321         EControlHaltEndpoint,                                // 09

   322         //

   323         EControlClearHaltEndpoint,                            // 10

   324         EControlSetDeviceControl,

   325         EControlReleaseDeviceControl,

   326         EControlEndpointZeroMaxPacketSizes,

   327         EControlSetEndpointZeroMaxPacketSize,

   328         EControlGetDeviceDescriptor,

   329         EControlSetDeviceDescriptor,

   330         EControlGetDeviceDescriptorSize,

   331         EControlGetConfigurationDescriptor,

   332         EControlSetConfigurationDescriptor,                    // 19

   333         //

   334         EControlGetConfigurationDescriptorSize,                // 20

   335         EControlGetInterfaceDescriptor,

   336         EControlSetInterfaceDescriptor,

   337         EControlGetInterfaceDescriptorSize,

   338         EControlGetEndpointDescriptor,

   339         EControlSetEndpointDescriptor,

   340         EControlGetEndpointDescriptorSize,

   341         EControlGetCSInterfaceDescriptor,

   342         EControlSetCSInterfaceDescriptor,

   343         EControlGetCSInterfaceDescriptorSize,                // 29

   344         //

   345         EControlGetCSEndpointDescriptor,                    // 30

   346         EControlSetCSEndpointDescriptor,

   347         EControlGetCSEndpointDescriptorSize,

   348         EControlSignalRemoteWakeup,

   349         EControlGetStringDescriptorLangId,

   350         EControlSetStringDescriptorLangId,

   351         EControlGetManufacturerStringDescriptor,

   352         EControlSetManufacturerStringDescriptor,

   353         EControlRemoveManufacturerStringDescriptor,

   354         EControlGetProductStringDescriptor,                    // 39

   355         //

   356         EControlSetProductStringDescriptor,                    // 40

   357         EControlRemoveProductStringDescriptor,

   358         EControlGetSerialNumberStringDescriptor,

   359         EControlSetSerialNumberStringDescriptor,

   360         EControlRemoveSerialNumberStringDescriptor,

   361         EControlGetConfigurationStringDescriptor,

   362         EControlSetConfigurationStringDescriptor,

   363         EControlRemoveConfigurationStringDescriptor,

   364         EControlDeviceDisconnectFromHost,

   365         EControlDeviceConnectToHost,                        // 49

   366         //

   367         EControlDevicePowerUpUdc,                            // 50

   368         EControlDumpRegisters,

   369         EControlAllocateEndpointResource,

   370         EControlDeAllocateEndpointResource,

   371         EControlQueryEndpointResourceUse,

   372         EControlGetEndpointZeroMaxPacketSize,

   373         EControlGetDeviceQualifierDescriptor,

   374         EControlSetDeviceQualifierDescriptor,

   375         EControlGetOtherSpeedConfigurationDescriptor,

   376         EControlSetOtherSpeedConfigurationDescriptor,        // 59

   377         //

   378         EControlCurrentlyUsingHighSpeed,                    // 60

   379         EControlSetStringDescriptor,

   380         EControlGetStringDescriptor,

   381         EControlRemoveStringDescriptor,

   382         EControlSetOtgDescriptor,

   383         EControlGetOtgDescriptor,

   384         EControlGetOtgFeatures, 

   385         EControlRealizeInterface,

   386         EControlStartNextInAlternateSetting    

   387         };

   388 

   389 

   390  // const static TUint KFieldIdPos     = 0;

   391     const static TUint KFieldIdMask    = 0xFF;

   392     const static TUint KFieldBuffPos   = 8;

   393     const static TUint KFieldBuffMask  = 0x3F;

   394     const static TUint KFieldFlagsPos  = 14;

   395     const static TUint KFieldFlagsMask = 0xFFFF;

   396 

   397 

   398 public:

   399 

   400 #ifndef __KERNEL_MODE__

   401 

   402     /** Opens a channel.

   403 

   404         @param aUnit This should be 0 (zero).

   405 

   406         @return KErrNone if successful.

   407     */

   408     inline TInt Open(TInt aUnit);

   409 

   410     inline TVersion VersionRequired() const;

   411 

   412     /** Stalls ep0 to signal command fault to the host.

   413 

   414         @return KErrNone if successful.

   415     */

   416     inline TInt EndpointZeroRequestError();

   417 

   418     /** Retrieves the capabilities of all the endpoints on the device.

   419 

   420         Suggested use is as follows:

   421 

   422         @code

   423         TUsbcEndpointData data[KUsbcMaxEndpoints];

   424         TPtr8 dataPtr(reinterpret_cast<TUint8*>(data), sizeof(data), sizeof(data));

   425         ret = usbPort.EndpointCaps(dataPtr);

   426         @endcode

   427 

   428         @param aEpCapsBuf A descriptor encapsulating an array of TUsbcEndpointData.

   429 

   430         @return KErrNone if successful.

   431     */

   432     inline TInt EndpointCaps(TDes8& aEpCapsBuf);

   433 

   434     /** Retrieves the capabilities of the USB device.

   435 

   436         @see TUsbDeviceCaps

   437 

   438         @param aDevCapsBuf A TUsbDeviceCaps object.

   439 

   440         @return KErrNone if successful.

   441     */

   442     inline TInt DeviceCaps(TUsbDeviceCaps& aDevCapsBuf);

   443 

   444     /** Copies the current alternate setting for this interface into aInterfaceNumber

   445         For USB Interfaces whose main interface is active, this will be 0 (zero).

   446 

   447         @param aInterfaceNumber Current alternate setting for this interface is copied into this.

   448 

   449         @return KErrNone if successful.

   450     */

   451     inline TInt GetAlternateSetting(TInt& aInterfaceNumber);

   452 

   453     /** Copies the current device status into aDeviceStatus.

   454 

   455         @param aDeviceStatus Current device status is copied into this.

   456 

   457         @return KErrNone if successful

   458     */

   459     inline TInt DeviceStatus(TUsbcDeviceState& aDeviceStatus);

   460 

   461     /** Copies the current endpoint status into aEndpointStatus.

   462 

   463         @param aEndpoint Endpoint number valid for the current alternate setting.

   464         @param aEndpointStatus The current endpoint status, might be stalled, not stalled or unknown.

   465 

   466         @return KErrNone if successful.

   467     */

   468     inline TInt EndpointStatus(TInt aEndpoint, TEndpointState& aEndpointStatus);

   469 

   470 

   471     /** Requests that a zero length status packet be sent to the host in response

   472         to a class or vendor specific ep0 SETUP packet.

   473 

   474         @return KErrNone if successful.

   475     */

   476     inline TInt SendEp0StatusPacket();

   477 

   478     /** Stalls endpoint aEndpoint, usually to indicate an error condition with a previous command.

   479         The host will normally send a SET_FEATURE command on ep0 to acknowledge and clear the stall.

   480 

   481         @return KErrNone if successful.

   482     */

   483     inline TInt HaltEndpoint(TInt aEndpoint);

   484 

   485     /** Clears the stall condition on endpoint aEndpoint. This is inluded for symmetry and test purposes.

   486 

   487         @return KErrNone if successful.

   488     */

   489     inline TInt ClearHaltEndpoint(TInt aEndpoint);

   490 

   491     /** Requests that device control be allocated to this channel.

   492 

   493         @return KErrNone if successful.

   494     */

   495     inline TInt SetDeviceControl();

   496 

   497     /** Relinquishes device control previously allocated to this channel.

   498 

   499         @return KErrNone if successful.

   500     */

   501     inline TInt ReleaseDeviceControl();

   502 

   503     /** Returns a bitmap of available ep0 maximum packet sizes.

   504 

   505         @return bitmap of available ep0 maximum packet sizes.

   506     */

   507     inline TUint EndpointZeroMaxPacketSizes();

   508 

   509     /** Requests that a maximum packet size of aMaxPacketSize be set on ep0.

   510 

   511         @param aMaxPacketSize The maximum packet size.

   512 

   513         @return KErrNone if successful.

   514     */

   515     inline TInt SetEndpointZeroMaxPacketSize(TInt aMaxPacketSize);

   516 

   517     /** Queries the current maximum packet size on ep0.

   518 

   519         @return The currently set maximum packet size on ep0.

   520     */

   521     inline TInt GetEndpointZeroMaxPacketSize();

   522 

   523     /** Copies the current device descriptor into aDeviceDescriptor.

   524 

   525         @param aDeviceDescriptor Receives the current device descriptor.

   526 

   527         @return KErrNone if successful.

   528     */

   529     inline TInt GetDeviceDescriptor(TDes8& aDeviceDescriptor);

   530 

   531     /** Sets the contents of aDeviceDescriptor to be the current device descriptor.

   532 

   533         @param aDeviceDescriptor Contains the device descriptor.

   534 

   535         @return KErrNone if successful.

   536     */

   537     inline TInt SetDeviceDescriptor(const TDesC8& aDeviceDescriptor);

   538 

   539     /** Gets the size of the current device descriptor. This is unlikely to be anything other than 9.

   540 

   541         @param aSize Receives the size of the current device descriptor.

   542 

   543         @return KErrNone if successful.

   544     */

   545     inline TInt GetDeviceDescriptorSize(TInt& aSize);

   546 

   547     /** Copies the current configuration descriptor into aConfigurationDescriptor.

   548 

   549         @param aConfigurationDescriptor Receives the current configuration descriptor.

   550 

   551         @return KErrNone if successful.

   552     */

   553     inline TInt GetConfigurationDescriptor(TDes8& aConfigurationDescriptor);

   554 

   555     /** Sets the contents of aConfigurationDescriptor to be the current configuration descriptor.

   556 

   557         @param aConfigurationDescriptor Contains the configuration descriptor.

   558 

   559         @return KErrNone if successful.

   560     */

   561     inline TInt SetConfigurationDescriptor(const TDesC8& aConfigurationDescriptor);

   562 

   563     /** Gets the size of the current configuration descriptor.

   564 

   565         @param aSize Receives the size of the current configuration descriptor.

   566 

   567         @return KErrNone if successful.

   568     */

   569     inline TInt GetConfigurationDescriptorSize(TInt& aSize);

   570 

   571     /** Copies the interface descriptor into aInterfaceDescriptor for the interface with alternate

   572         setting aSettingNumber, 0 for the main interface.

   573 

   574         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   575         @param aInterfaceDescriptor Receives the interface descriptor.

   576 

   577         @return KErrNone if successful.

   578     */

   579     inline TInt GetInterfaceDescriptor(TInt aSettingNumber, TDes8& aInterfaceDescriptor);

   580 

   581     /** Sets the interface descriptor contained in aInterfaceDescriptor for the interface with

   582         alternate setting aSettingNumber, 0 for the main interface, for transmission to the host

   583         during enumeration.

   584 

   585         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   586         @param aInterfaceDescriptor Contains the interface descriptor to be set.

   587 

   588         @return KErrNone if successful.

   589     */

   590     inline TInt SetInterfaceDescriptor(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor);

   591 

   592     /** Copies the size of the interface descriptor for the interface with alternate

   593         setting aSettingNumber, 0 for the main interface, into aSize.

   594 

   595         @param aSettingNumber The alternate setting.

   596         @param aSize receives the size of the interface descriptor.

   597 

   598         @return KErrNone if successful.

   599     */

   600     inline TInt GetInterfaceDescriptorSize(TInt aSettingNumber, TInt& aSize);

   601 

   602     /** Copies the endpoint descriptor for logical endpoint number aEndpointNumber into aEndpointDescriptor

   603         for the interface with alternate setting aSettingNumber, 0 for the main interface.

   604 

   605         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   606         @param aEndpointNumber The endpoint number of the endpoint.

   607         @param aEndpointDescriptor Receives the endpoint descriptor.

   608 

   609         @return KErrNone if successful.

   610     */

   611     inline TInt GetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, TDes8& aEndpointDescriptor);

   612 

   613     /** Sets the endpoint descriptor for logical endpoint number aEndpointNumber contained in

   614         aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface,

   615         for transmission to the host during enumeration.

   616 

   617         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   618         @param aEndpointNumber Valid endpoint number on this interface.

   619         @param aEndpointDescriptor Contains the endpoint descriptor to be set.

   620 

   621         @return KErrNone if successful.

   622     */

   623     inline TInt SetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber,

   624                                       const TDesC8& aEndpointDescriptor);

   625 

   626     /** Copies the size of the endpoint descriptor for logical endpoint number aEndpointNumber for the

   627         interface with alternate setting aSettingNumber, 0 for the main interface, into aSize.

   628 

   629         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   630         @param aEndpointNumber Valid endpoint number on this interface.

   631         @param aSize Receives the size of the endpoint descriptor.

   632 

   633         @return KErrNone if successful.

   634     */

   635     inline TInt GetEndpointDescriptorSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize);

   636 

   637     /** Get OTG descriptor size

   638 

   639         @param aSize TInt Reference which contains OTG descriptor size on return.

   640     */

   641     inline void GetOtgDescriptorSize(TInt& aSize);

   642 

   643     /** Get OTG descriptor of USB on-the-go feature.

   644 

   645         @param aOtgDesc User-side buffer to store copy of descriptor.

   646 

   647         @return KErrNone if successful.

   648     */

   649     inline TInt GetOtgDescriptor(TDes8& aOtgDesc);

   650 

   651     /** Set OTG descriptor by user to enable/disable USB on-the-go feature.

   652 

   653         @param aOtgDesc Descriptor buffer containing OTG features.

   654 

   655         @return KErrNone if successful.

   656     */

   657     inline TInt SetOtgDescriptor(const TDesC8& aOtgDesc);

   658 

   659     /** Copies the current device_qualifier descriptor into aDescriptor.

   660 

   661         @param aDescriptor Receives the current device_qualifier descriptor.

   662 

   663         @return KErrNone if successful.

   664     */

   665     inline TInt GetDeviceQualifierDescriptor(TDes8& aDescriptor);

   666 

   667     /** Sets the device_qualifier descriptor to the contents of aDescriptor.

   668 

   669         @param aDescriptor Contains the new device_qualifier descriptor.

   670 

   671         @return KErrNone if successful.

   672     */

   673     inline TInt SetDeviceQualifierDescriptor(const TDesC8& aDescriptor);

   674 

   675     /** Copies the current other_speed_configuration descriptor into aDescriptor.

   676 

   677         @param aDescriptor Receives the current other_speed_configuration descriptor.

   678 

   679         @return KErrNone if successful.

   680     */

   681     inline TInt GetOtherSpeedConfigurationDescriptor(TDes8& aDescriptor);

   682 

   683     /** Sets the other_speed_configuration descriptor to the contents of aDescriptor.

   684 

   685         @param aDescriptor Contains the new other_speed_configuration descriptor.

   686 

   687         @return KErrNone if successful.

   688     */

   689     inline TInt SetOtherSpeedConfigurationDescriptor(const TDesC8& aDescriptor);

   690 

   691     /** Copies the class specific interface descriptor block into aInterfaceDescriptor for the interface

   692         with alternate setting aSettingNumber, 0 for the main interface.

   693 

   694         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   695         @param aInterfaceDescriptor Contains the interface descriptor to be set.

   696 

   697         @return KErrNone if successful.

   698     */

   699     inline TInt GetCSInterfaceDescriptorBlock(TInt aSettingNumber, TDes8& aInterfaceDescriptor);

   700 

   701     /** aSettingNumber is the alternate interface setting, 0 for the main interface, that the descriptor block

   702         aDes should be attached to. aDes is a block of data containing at least one class specific descriptor

   703         for transmission during enumeration after the class interface descriptor (or alternate interface

   704         descriptor) has been sent, but before the endpoint descriptors belonging to this interface are sent.

   705         aDes may contain as many descriptors as are necessary or only one. SetCSInterfaceDescriptorBlock()

   706         should be called at any time after SetInterface() has been called to establish a main interface or an

   707         alternate interface. More than one call may be made - the data blocks will be concatenated prior to

   708         sending. No checking or validation of the contents of aDes will be made and it is the caller's

   709         responsibility to ensure that the data supplied is correct and appropriate to the interface identified

   710         by aSettingNumber.

   711 

   712         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   713         @param aInterfaceDescriptor Contains the interface descriptor to be set.

   714 

   715         @return KErrNone if successful.

   716     */

   717     inline TInt SetCSInterfaceDescriptorBlock(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor);

   718 

   719     /** Copies the size of the class specific interface descriptor block for the interface with alternate

   720         setting aSettingNumber, 0 for the main interface, into aSize.

   721 

   722         @param aSettingNumber The alternate setting number.

   723         @param aSize receives the size of the interface descriptor.

   724 

   725         @return KErrNone if successful.

   726     */

   727     inline TInt GetCSInterfaceDescriptorBlockSize(TInt aSettingNumber, TInt& aSize);

   728 

   729     /** Copies the class specific endpoint descriptor for logical endpoint number aEndpointNumber

   730         into aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main

   731         interface.

   732 

   733         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   734         @param aEndpointNumber Valid endpoint number on this interface.

   735         @param aEndpointDescriptor Receives the endpoint descriptor.

   736 

   737         @return KErrNone if successful.

   738     */

   739     inline TInt GetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber,

   740                                              TDes8& aEndpointDescriptor);

   741 

   742     /** Sets the class specific endpoint descriptor for logical endpoint number aEndpointNumber contained in

   743         aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface,

   744         for transmission to the host during enumeration.

   745 

   746         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   747         @param aEndpointNumber Valid endpoint number on this interface.

   748         @param aEndpointDescriptor Contains the endpoint descriptor to be set.

   749 

   750         @return KErrNone if successful.

   751     */

   752     inline TInt SetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber,

   753                                              const TDesC8& aEndpointDescriptor);

   754 

   755     /** Copies the size of the class specific endpoint descriptor block for logical endpoint number

   756         aEndpointNumber for the interface with alternate setting aSettingNumber, 0 for the main interface,

   757         into aSize.

   758 

   759         @param aSettingNumber Alternate setting number on the interface, 0 for the main interface.

   760         @param aEndpointNumber Valid endpoint number on this interface.

   761         @param aSize On return, contains the size of the class specific endpoint descriptor block.

   762 

   763         @return KErrNone if successful.

   764     */

   765     inline TInt GetCSEndpointDescriptorBlockSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize);

   766 

   767     /** Generates a Remote Wakeup bus condition.

   768         The capability of the device to generate Remote Wakeup signalling is enquired in

   769         RDevUsbcClient::DeviceCaps.

   770 

   771         @return KErrNone if this signalling is possible and the signal has been generated.

   772     */

   773     inline TInt SignalRemoteWakeup();

   774 

   775     /** Simulates a physical removal of the USB cable by disabling the D+/- pull-ups.The iConnect member of

   776         TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality is

   777         supported.

   778 

   779         @return KErrNone if successful.

   780     */

   781     inline TInt DeviceDisconnectFromHost();

   782 

   783     /** Simulates a physical insertion of the USB cable by enabling the D+/- pull-ups.The iConnect member

   784         of TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(),  indicates whether this functionality

   785         is supported.

   786 

   787         @return KErrNone if successful.

   788     */

   789     inline TInt DeviceConnectToHost();

   790 

   791     /** Powers up the UDC and connects it to the bus if one or more interfaces exist.

   792 

   793         @return KErrNone if UDC successfully powered up, KErrNotReady if no

   794         interfaces have been registered yet, KErrHardwareNotAvailable if UDC

   795         couldn't be activated.

   796     */

   797     inline TInt PowerUpUdc();

   798 

   799     /** Enquires about the current operating speed of the UDC.

   800 

   801         @return ETrue if the UDC is currently operating at High speed, EFalse otherwise.

   802     */

   803     inline TBool CurrentlyUsingHighSpeed();

   804 

   805     /** Allocates the use of aResource to aEndpoint. It will be used from when the current bus transfer    has been

   806         completed.

   807 

   808         @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint

   809         behaviour. aResource is not a bitmap and TEndpointResource values should not be combined.

   810         @param aEndpoint The endpoint number to which the resource is to be allocated.

   811 

   812         @return KErrNone if successful, KErrInUse if the resource is already consumed and cannot be allocated,

   813         KErrNotSupported if the endpoint does not support the resource requested.

   814 

   815         @publishedPartner @deprecated

   816     */

   817     inline TInt AllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource);

   818 

   819     /** Deallocates the use of aResource aEndpoint or ends a specified endpoint behaviour.

   820 

   821         @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint

   822         behaviour. aResource is not a bitmap and TEndpointResource values should not be combined.

   823         @param aEndpoint The endpoint number from which the resource is to be removed.

   824 

   825         @return KErrNone if the resource has been successfully deallocated, KErrNotSupported if the endpoint

   826         does not support the resource requested.

   827 

   828         @publishedPartner @deprecated

   829     */

   830     inline TInt DeAllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource);

   831 

   832     /** Queries endpoint resource use.

   833 

   834         @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint

   835         behaviour. aResource is not a bitmap and TEndpointResource values should not be combined.

   836         @param aEndpoint The endpoint number at which the resource is to be queried.

   837 

   838         @return ETrue is the specified resource is in use at the endpoint and EFalse if not.

   839     */

   840     inline TBool QueryEndpointResourceUse(TInt aEndpoint, TUsbcEndpointResource aResource);

   841 

   842     /** Request (i.e. claim for this channel) up to five endpoints and set the class type for this USB

   843         interface. 'aInterfaceData' is a package buffer which describes the interface and all the endpoints

   844         being requested by the driver for this interface.

   845 

   846         @param aInterfaceNumber Distinguishes between alternate interfaces. If these are not be used then this

   847         should always be zero. If this parameter is used, then its value must be one more than that of the

   848         proceeding alternate interface.

   849         @param aInterfaceData A package buffer which describes the interface and all the endpoints being

   850         requested by the driver for this interface.

   851 

   852 

   853         @return KErrInUse if any of the endpoints being requested have already been claimed by another channel.

   854         KErrNotSupported if an endpoint with all of the specified properties is not supported on this

   855         platform. KErrNoMemory if insufficient memory is available to complete the operation.

   856     */

   857     inline TInt SetInterface(TInt aInterfaceNumber, TUsbcScInterfaceInfoBuf& aInterfaceData);

   858 

   859 

   860     /**

   861         This method should be called after SetInterface has been called for all possible alternative settings.

   862         Calling this invalidates further calls to SetInterface. On success, a chunk handle is created and

   863         passed back though aChunk.   This is needed for the user side to access the shared chunk where the

   864         data is stored.  Note that if you are using the BIL (described later), then FinalizeInterface (...)

   865         should be used instead, which will call this method.

   866         

   867         @return KErrNone on successful completion, or one of the system wide error codes.

   868     */

   869     inline TInt RealizeInterface(RChunk& aChunk);

   870 

   871 

   872     /** Release an interface previously claimed by this channel. Alternate interfaces need to be released

   873         in strict descending order, starting with the last (i.e. highest numbered) one.

   874         It is not necessary to release an interface that wasn't successfully requested.

   875 

   876         @param aInterfaceNumber Specifies the alternate setting number 'aInterfaceNum' of the interface to be

   877         released.

   878 

   879         @return KErrNone if successful. KErrArgument if the alternate setting doesn't exist or is released out

   880         of order.

   881     */

   882     inline TInt ReleaseInterface(TInt aInterfaceNumber);

   883 

   884     /** Copies the current string descriptor language ID (LANGID) code into the aLangId argument. Even though

   885         the USB spec allows for the existence of a whole array of LANGID codes, we only support one.

   886 

   887         @param aLangId Receives the LANGID code.

   888 

   889         @return KErrNone if successful, KErrArgument if problem with argument (memory cannot be written to, etc.).

   890     */

   891     inline TInt GetStringDescriptorLangId(TUint16& aLangId);

   892 

   893     /** Sets the string descriptor language ID (LANGID). Even though the USB spec allows for the existence of

   894         a whole array of LANGID codes, we only support one.

   895 

   896         @param aLangId The LANGID code to be set.

   897 

   898         @return KErrNone if successful.

   899     */

   900     inline TInt SetStringDescriptorLangId(TUint16 aLangId);

   901 

   902     /** Copies the string descriptor identified by the iManufacturer index field of the Standard Device

   903         Descriptor into the aString argument.

   904 

   905         @param aString Receives manufacturer string.

   906 

   907         @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire

   908         descriptor, KErrNotFound if the string descriptor couldn't be found.

   909     */

   910     inline TInt GetManufacturerStringDescriptor(TDes16& aString);

   911 

   912     /** Sets the string descriptor identified by the iManufacturer index field of the Standard Device

   913         Descriptor to the aString argument.

   914 

   915         @param aString Contains the new manufacturer string descriptor.

   916 

   917         @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from

   918         aString (in which case the old string descriptor will be preserved).

   919     */

   920     inline TInt SetManufacturerStringDescriptor(const TDesC16& aString);

   921 

   922     /** Removes (deletes) the string descriptor identified by the iManufacturer index field of the Standard

   923         Device Descriptor and sets that field to zero.

   924 

   925         @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found.

   926     */

   927     inline TInt RemoveManufacturerStringDescriptor();

   928 

   929     /** Retrieves the string descriptor identified by the iProduct index field of the Standard Device

   930         Descriptor into the aString argument.

   931 

   932         @param aString Receives product string.

   933 

   934         @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire

   935         descriptor, KErrNotFound if the string descriptor couldn't be found.

   936     */

   937     inline TInt GetProductStringDescriptor(TDes16& aString);

   938 

   939     /** Sets the string descriptor identified by the iProduct index field of the Standard Device Descriptor to

   940         the aString argument.

   941 

   942         @param aString Contains the new product string descriptor.

   943 

   944         @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from

   945         aString (in which case the old string descriptor will be preserved).

   946     */

   947     inline TInt SetProductStringDescriptor(const TDesC16& aString);

   948 

   949     /** Removes (deletes) the string descriptor identified by the iProduct index field of the Standard Device

   950         Descriptor and sets that field to zero.

   951 

   952         @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found.

   953     */

   954     inline TInt RemoveProductStringDescriptor();

   955 

   956     /** Retrieves the string descriptor identified by the iSerialNumber index field of the Standard Device

   957         Descriptor into the aString argument.

   958 

   959         @param aString Receives product string.

   960 

   961         @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire

   962         descriptor, KErrNotFound if the string descriptor couldn't be found.

   963     */

   964     inline TInt GetSerialNumberStringDescriptor(TDes16& aString);

   965 

   966     /** Sets the string descriptor identified by the iSerialNumber index field of the Standard Device

   967         Descriptor to the aString argument.

   968 

   969         @param aString Contains the new serial number string descriptor.

   970 

   971         @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from

   972         aString (in which case the old string descriptor will be preserved).

   973     */

   974     inline TInt SetSerialNumberStringDescriptor(const TDesC16& aString);

   975 

   976     /** Removes (deletes) the string descriptor identified by the iSerialNumber index field of the Standard

   977         Device Descriptor and sets that field to zero.

   978 

   979         @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found.

   980     */

   981     inline TInt RemoveSerialNumberStringDescriptor();

   982 

   983     /** Retrieves the string descriptor identified by the iConfiguration index field of the (first) Standard

   984         Configuration Descriptor into the aString argument.

   985 

   986         @param aString Receives configuration string.

   987 

   988         @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire

   989         descriptor, KErrNotFound if the string descriptor couldn't be found.

   990     */

   991     inline TInt GetConfigurationStringDescriptor(TDes16& aString);

   992 

   993     /** Sets the string descriptor identified by the iConfiguration index field of the Standard Configuration

   994         Descriptor to the aString argument.

   995 

   996         @param aString Contains the new serial number string descriptor.

   997 

   998         @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from

   999         aString (in which case the old string descriptor will be preserved).

  1000     */

  1001     inline TInt SetConfigurationStringDescriptor(const TDesC16& aString);

  1002 

  1003     /** Removes (deletes) the string descriptor identified by the iConfiguration index field of the Standard

  1004         Configuration Descriptor and sets that field to zero.

  1005 

  1006         @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found.

  1007     */

  1008     inline TInt RemoveConfigurationStringDescriptor();

  1009 

  1010     /** Copies the string of the USB string descriptor at the specified index in the string descriptor array

  1011         into the aString argument.

  1012 

  1013         Although this function can also be used for it, for querying most standard string descriptors

  1014         there exists a set of dedicated access functions.

  1015 

  1016         @see RDevUsbcClient::GetStringDescriptorLangId

  1017         @see RDevUsbcClient::GetManufacturerStringDescriptor

  1018         @see RDevUsbcClient::GetProductStringDescriptor

  1019         @see RDevUsbcClient::GetSerialNumberStringDescriptor

  1020         @see RDevUsbcClient::GetConfigurationStringDescriptor

  1021 

  1022         @param aIndex The position of the string descriptor in the string descriptor array.

  1023         @param aString The target location for the string descriptor copy.

  1024 

  1025         @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index,

  1026         KErrArgument if MaxLength() of aString is too small to hold the entire descriptor.

  1027     */

  1028     inline TInt GetStringDescriptor(TUint8 aIndex, TDes16& aString);

  1029 

  1030     /** Sets the aString argument to be the string of a USB string descriptor at the specified index in the

  1031         string descriptor array. If a string descriptor already exists at that position then its string will

  1032         be replaced.

  1033 

  1034         Care should be taken, when choosing aIndex, not to inadvertently overwrite one of the standard

  1035         string descriptors.    For their manipulation there exists a set of dedicated access functions.

  1036 

  1037         @see RDevUsbcClient::SetStringDescriptorLangId

  1038         @see RDevUsbcClient::SetManufacturerStringDescriptor

  1039         @see RDevUsbcClient::SetProductStringDescriptor

  1040         @see RDevUsbcClient::SetSerialNumberStringDescriptor

  1041         @see RDevUsbcClient::SetConfigurationStringDescriptor

  1042 

  1043         @param aIndex The position of the string descriptor in the string descriptor array.

  1044         @param aString Contains the string descriptor to be set.

  1045 

  1046         @return KErrNone if successful, KErrArgument if aIndex is invalid, KErrNoMemory if no memory

  1047         is available to store the new string (an existing descriptor at that index will be preserved).

  1048     */

  1049     inline TInt SetStringDescriptor(TUint8 aIndex, const TDesC16& aString);

  1050 

  1051     /** Removes (deletes) the USB string descriptor at the specified index in the string descriptor array.

  1052         The position in the array of other string descriptors is not affected.

  1053 

  1054         Care should be taken, when choosing aIndex, not to inadvertently delete a standard string descriptor

  1055         (also because index references from non-string descriptors would be invalidated). For the deletion

  1056         of most standard string descriptors there exists a set of dedicated functions.

  1057 

  1058         @see RDevUsbcClient::RemoveManufacturerStringDescriptor

  1059         @see RDevUsbcClient::RemoveProductStringDescriptor

  1060         @see RDevUsbcClient::RemoveSerialNumberStringDescriptor

  1061         @see RDevUsbcClient::RemoveConfigurationStringDescriptor

  1062 

  1063         @param aIndex The position of the string descriptor in the string descriptor array.

  1064 

  1065         @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index.

  1066     */

  1067     inline TInt RemoveStringDescriptor(TUint8 aIndex);

  1068 

  1069 

  1070 

  1071     /**  Requests notification for when there is data available on the buffer indicated.  If the buffer

  1072          already has data in it, it will return immediately, otherwise it will block until there is.

  1073 

  1074     If the BIL methods are being used (recommended), then this method should not be called directly,

  1075     using TEndpointBuffer::GetBuffer instead.

  1076 

  1077     @param aBufferNumber Indicates the buffer for which the caller wishes to know about data 

  1078     additions.  The buffer needed of any given endpoint can be found by inspecting the alternative

  1079     setting table, in the chunk header.  The location of the buffer can be found by looking at the

  1080     buffer offset table, also in the chunk header. 

  1081 

  1082     @param aStatus The request status where notification of completion is directed. KErrCancel is

  1083     returned if the asynchronous operation was cancelled.

  1084 

  1085     @param aLength A preference for the quantity of data to be read.  This value is only a 

  1086     suggestion and my be ignored.  The default value of 0 indicates no preference.

  1087 

  1088     @return KErrNone on success, or KErrArgument if the buffer number is invalid.    

  1089     */

  1090     inline TInt ReadDataNotify(TInt aBufferNumber, TRequestStatus& aStatus, TInt aLength=0);

  1091 

  1092 

  1093     /**  Requests the LDD to write the contents of the given buffer to the USB hardware.  Notification is

  1094     given when this is complete.  More then one write request can be queued on any one endpoint, to allow

  1095     for less Hardware idling between buffers.

  1096 

  1097     If the BIL methods are being used (recommended), then this method should not be called directly,

  1098     using TEndpointBuffer::WriteBuffer instead.

  1099 

  1100     @param aBufferNumber represents the buffer number of the buffer of which the caller has placed the

  1101     data. As described with ReadDataNotify(...), details of the buffers can be found in the chunk header.

  1102 

  1103     @param aStart Represents the start offset of the data within the chunk.  This start location must be

  1104     aligned to a multiple of the maximum packet size for the endpoint, so that the data can be DMAed

  1105     straight out of the buffer.

  1106 

  1107     @param aLength Represents the amount of data to be sent to the host in bytes.

  1108 

  1109     @param aFlags Is a bitfield, where bit 0 should be set if a ZLP is to be sent to the host after the

  1110     current transaction.  All other bits are reserved for future use.

  1111 */

  1112     inline void WriteData(TInt aBufferNumber, TUint aStart, TUint aLength, TUint aFlags, TRequestStatus& aStatus);

  1113 

  1114 

  1115 

  1116     /** Cancels an outstanding read request on endpoint buffer aBufferNumber.

  1117 

  1118         @param aBufferNumber The endpoint buffer number whose read is to be cancelled.

  1119     */

  1120     inline void ReadCancel(TInt aBufferNumber);

  1121 

  1122 

  1123     /** Cancels an outstanding write request on endpoint buffer aBufferNumber.

  1124 

  1125         @param aBufferNumber The endpoint buffer number whose write is to be cancelled.

  1126     */

  1127     inline void WriteCancel(TInt aBufferNumber);

  1128 

  1129     /** Cancels any transfer on any endpoint buffer specified in aBufferMask.

  1130 

  1131         @code

  1132         // Cancel transfer requests on buffers 1, 2, 3 & 4

  1133         usbPort.EndpointTransferCancel(1 | 2 | 4 | 8);

  1134         @endcode