1 // Copyright (c) 2002-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/usbcdesc.h

    15 // USB descriptors and their management.

    16 // 

    17 //

    18 

    19 /**

    20  @file usbcdesc.h

    21  @internalTechnology

    22 */

    23 

    24 #ifndef __USBCDESC_H__

    25 #define __USBCDESC_H__

    26 

    27 #include <kernel/kernel.h>

    28 

    29 

    30 // Hard-wired positions of some descriptors in iDescriptors array (whether present or not):

    31 static const TInt KDescPosition_Device           = 0;

    32 static const TInt KDescPosition_DeviceQualifier  = 1;

    33 static const TInt KDescPosition_OtherSpeedConfig = 2;

    34 static const TInt KDescPosition_Config           = 3;

    35 static const TInt KDescPosition_Otg              = 4;

    36 static const TInt KDescPosition_FirstAvailable   = 5;

    37 

    38 // Hard-wired positions of string descriptors in iStrings array (whether present or not):

    39 static const TInt KStringPosition_Langid           = 0;

    40 static const TInt KStringPosition_Manufact         = 1;

    41 static const TInt KStringPosition_Product          = 2;

    42 static const TInt KStringPosition_Serial           = 3;

    43 static const TInt KStringPosition_Config           = 4;

    44 static const TInt KStringPosition_OtherSpeedConfig = 5;

    45 static const TInt KStringPosition_FirstAvailable   = 6;

    46 

    47 

    48 NONSHARABLE_CLASS(TUsbcDescriptorBase)

    49     {

    50 public:

    51     virtual ~TUsbcDescriptorBase();

    52     void SetByte(TInt aPosition, TUint8 aValue);

    53     void SetWord(TInt aPosition, TUint16 aValue);

    54     TUint8 Byte(TInt aPosition) const;

    55     TUint16 Word(TInt aPosition) const;

    56     void GetDescriptorData(TDes8& aBuffer) const;

    57     TInt GetDescriptorData(TUint8* aBuffer) const;

    58     TInt GetDescriptorData(TUint8* aBuffer, TUint aMaxSize) const;

    59     const TDes8& DescriptorData() const;

    60     TDes8& DescriptorData();

    61     TUint Size() const;

    62     TUint8 Type() const;

    63     virtual void UpdateFs();

    64     virtual void UpdateHs();

    65 protected:

    66     TUsbcDescriptorBase();

    67     void SetBufferPointer(const TDesC8& aDes);

    68 private:

    69 #ifdef USB_SUPPORTS_SET_DESCRIPTOR_REQUEST

    70     TUint8 iIndex;                                            // only needed for SET_DESCRIPTOR

    71 #endif

    72     TPtr8 iBufPtr;

    73     };

    74 

    75 

    76 NONSHARABLE_CLASS(TUsbcDeviceDescriptor) : public TUsbcDescriptorBase

    77     {

    78 public:

    79     /** aMaxPacketSize0 should be the Ep0 max packet size for FS operation (as the HS size

    80         is fixed and known).

    81     */

    82     static TUsbcDeviceDescriptor* New(TUint8 aDeviceClass, TUint8 aDeviceSubClass,

    83                                       TUint8 aDeviceProtocol, TUint8 aMaxPacketSize0,

    84                                       TUint16 aVendorId, TUint16 aProductId,

    85                                       TUint16 aDeviceRelease, TUint8 aNumConfigurations);

    86     virtual void UpdateFs();

    87     virtual void UpdateHs();

    88 private:

    89     TUsbcDeviceDescriptor();

    90     TInt Construct(TUint8 aDeviceClass, TUint8 aDeviceSubClass, TUint8 aDeviceProtocol,

    91                    TUint8 aMaxPacketSize0, TUint16 aVendorId, TUint16 aProductId,

    92                    TUint16 aDeviceRelease, TUint8 aNumConfigurations);

    93     TBuf8<KUsbDescSize_Device> iBuf;

    94     TUint8 iEp0Size_Fs;                                        // holds Ep0 size for FS (could be < 64)

    95     };

    96 

    97 

    98 NONSHARABLE_CLASS(TUsbcDeviceQualifierDescriptor) : public TUsbcDescriptorBase

    99     {

   100 public:

   101     /** aMaxPacketSize0 should be the Ep0 max packet size for FS operation (as the HS size

   102         is fixed and known).

   103     */

   104     static TUsbcDeviceQualifierDescriptor* New(TUint8 aDeviceClass, TUint8 aDeviceSubClass,

   105                                                TUint8 aDeviceProtocol, TUint8 aMaxPacketSize0,

   106                                                TUint8 aNumConfigurations, TUint8 aReserved=0);

   107     virtual void UpdateFs();

   108     virtual void UpdateHs();

   109 private:

   110     TUsbcDeviceQualifierDescriptor();

   111     TInt Construct(TUint8 aDeviceClass, TUint8 aDeviceSubClass, TUint8 aDeviceProtocol,

   112                    TUint8 aMaxPacketSize0, TUint8 aNumConfigurations, TUint8 aReserved);

   113     TBuf8<KUsbDescSize_DeviceQualifier> iBuf;

   114     TUint8 iEp0Size_Fs;                                        // holds Ep0 size for FS (could be < 64)

   115     };

   116 

   117 

   118 NONSHARABLE_CLASS(TUsbcConfigDescriptor) : public TUsbcDescriptorBase

   119     {

   120 public:

   121     /** aMaxPower should be given here in milliamps (not mA/2). */

   122     static TUsbcConfigDescriptor* New(TUint8 aConfigurationValue, TBool aSelfPowered, TBool aRemoteWakeup,

   123                                       TUint16 aMaxPower);

   124 private:

   125     TUsbcConfigDescriptor();

   126     TInt Construct(TUint8 aConfigurationValue, TBool aSelfPowered, TBool aRemoteWakeup, TUint16 aMaxPower);

   127     TBuf8<KUsbDescSize_Config> iBuf;

   128     };

   129 

   130 

   131 // The Other_Speed_Configuration descriptor has same size and layout as the

   132 // standard Configuration descriptor, therefore we don't need a new definition.

   133 typedef TUsbcConfigDescriptor TUsbcOtherSpeedConfigDescriptor;

   134 

   135 

   136 NONSHARABLE_CLASS(TUsbcInterfaceDescriptor) : public TUsbcDescriptorBase

   137     {

   138 public:

   139     static TUsbcInterfaceDescriptor* New(TUint8 aInterfaceNumber, TUint8 aAlternateSetting, TInt NumEndpoints,

   140                                          const TUsbcClassInfo& aClassInfo);

   141 private:

   142     TUsbcInterfaceDescriptor();

   143     TInt Construct(TUint8 aInterfaceNumber, TUint8 aAlternateSetting, TInt aNumEndpoints,

   144                    const TUsbcClassInfo& aClassInfo);

   145     TBuf8<KUsbDescSize_Interface> iBuf;

   146     };

   147 

   148 

   149 NONSHARABLE_CLASS(TUsbcEndpointDescriptorBase) : public TUsbcDescriptorBase

   150     {

   151 public:

   152     virtual void UpdateFs();

   153     virtual void UpdateHs();

   154 protected:

   155     TInt Construct(const TUsbcEndpointInfo& aEpInfo);

   156     TUsbcEndpointDescriptorBase();

   157 protected:

   158     /** Stores the endpoint size to be used for FS. */

   159     TInt iEpSize_Fs;

   160     /** Stores the endpoint size to be used for HS. */

   161     TInt iEpSize_Hs;

   162     /** Stores the endpoint polling interval to be used for FS. */

   163     TInt iInterval_Fs;

   164     /** Stores the endpoint polling interval to be used for HS. */

   165     TInt iInterval_Hs;

   166     };

   167 

   168 

   169 NONSHARABLE_CLASS(TUsbcEndpointDescriptor) : public TUsbcEndpointDescriptorBase

   170     {

   171 public:

   172     static TUsbcEndpointDescriptor* New(TUint8 aEndpointAddress, const TUsbcEndpointInfo& aEpInfo);

   173 private:

   174     TUsbcEndpointDescriptor();

   175     TInt Construct(TUint8 aEndpointAddress, const TUsbcEndpointInfo& aEpInfo);

   176     TBuf8<KUsbDescSize_Endpoint> iBuf;

   177     };

   178 

   179 

   180 class TUsbcAudioEndpointDescriptor : public TUsbcEndpointDescriptorBase

   181     {

   182 public:

   183     static TUsbcAudioEndpointDescriptor* New(TUint8 aEndpointAddress, const TUsbcEndpointInfo& aEpInfo);

   184 private:

   185     TUsbcAudioEndpointDescriptor();

   186     TInt Construct(TUint8 aEndpointAddress, const TUsbcEndpointInfo& aEpInfo);

   187     TBuf8<KUsbDescSize_AudioEndpoint> iBuf;

   188     };

   189 

   190 

   191 NONSHARABLE_CLASS(TUsbcOtgDescriptor) : public TUsbcDescriptorBase

   192     {

   193 public:

   194     static TUsbcOtgDescriptor* New(TBool aHnpSupport, TBool aSrpSupport);

   195 private:

   196     TUsbcOtgDescriptor();

   197     TInt Construct(TBool aHnpSupport, TBool aSrpSupport);

   198     TBuf8<KUsbDescSize_Otg> iBuf;

   199     };

   200 

   201 

   202 NONSHARABLE_CLASS(TUsbcClassSpecificDescriptor) : public TUsbcDescriptorBase

   203     {

   204 public:

   205     virtual ~TUsbcClassSpecificDescriptor();

   206     static TUsbcClassSpecificDescriptor* New(TUint8 aType, TInt aSize);

   207 private:

   208     TUsbcClassSpecificDescriptor();

   209     TInt Construct(TUint8 aType, TInt aSize);

   210     HBuf8* iBuf;

   211     };

   212 

   213 

   214 NONSHARABLE_CLASS(TUsbcStringDescriptorBase)

   215     {

   216 public:

   217     virtual ~TUsbcStringDescriptorBase();

   218     TUint16 Word(TInt aPosition) const;

   219     void SetWord(TInt aPosition, TUint16 aValue);

   220     TInt GetDescriptorData(TUint8* aBuffer) const;

   221     TInt GetDescriptorData(TUint8* aBuffer, TUint aMaxSize) const;

   222     const TDes8& StringData() const;

   223     TDes8& StringData();

   224     TUint Size() const;

   225     void SetBufferPointer(const TDesC8& aDes);

   226 protected:

   227     TUsbcStringDescriptorBase();

   228     TBuf8<2> iSBuf;

   229     TPtr8 iBufPtr;

   230 private:

   231 //    TUint8 iIndex;                                            // not needed in DescriptorPool: position == index

   232     };

   233 

   234 

   235 NONSHARABLE_CLASS(TUsbcStringDescriptor) : public TUsbcStringDescriptorBase

   236     {

   237 public:

   238     virtual ~TUsbcStringDescriptor();

   239     static TUsbcStringDescriptor* New(const TDesC8& aString);

   240 private:

   241     TUsbcStringDescriptor();

   242     TInt Construct(const TDesC8& aString);

   243     HBuf8* iBuf;

   244     };

   245 

   246 

   247 // Currently we support only one language, and thus there's no need to provide

   248 // a LangId string descriptor with more than one array element.

   249 NONSHARABLE_CLASS(TUsbcLangIdDescriptor) : public TUsbcStringDescriptorBase

   250     {

   251 public:

   252     virtual ~TUsbcLangIdDescriptor();

   253     static TUsbcLangIdDescriptor* New(TUint16 aLangId);

   254 private:

   255     TUsbcLangIdDescriptor();

   256     TInt Construct(TUint16 aLangId);

   257     TBuf8<2> iBuf;

   258     };

   259 

   260 

   261 class TUsbcDescriptorPool

   262     {

   263 public:

   264     TUsbcDescriptorPool(TUint8* aEp0_TxBuf);

   265     ~TUsbcDescriptorPool();

   266     TInt Init(TUsbcDeviceDescriptor* aDeviceDesc, TUsbcConfigDescriptor* aConfigDesc,

   267               TUsbcLangIdDescriptor* aLangId, TUsbcStringDescriptor* aManufacturer,

   268               TUsbcStringDescriptor* aProduct, TUsbcStringDescriptor* aSerialNum,

   269               TUsbcStringDescriptor* aConfig, TUsbcOtgDescriptor* aOtgDesc);

   270     TInt InitHs();

   271     TInt UpdateDescriptorsFs();

   272     TInt UpdateDescriptorsHs();

   273 

   274     // Descriptors

   275     TInt FindDescriptor(TUint8 aType, TUint8 aIndex, TUint16 aLangid, TInt& aSize) const;

   276     void InsertDescriptor(TUsbcDescriptorBase* aDesc);

   277     void DeleteIfcDescriptor(TInt aNumber, TInt aSetting=0);

   278     // The TC in many of the following functions stands for 'ThreadCopy' because that's what happens there.

   279     TInt GetDeviceDescriptorTC(DThread* aThread, TDes8& aBuffer) const;

   280     TInt SetDeviceDescriptorTC(DThread* aThread, const TDes8& aBuffer);

   281     TInt GetConfigurationDescriptorTC(DThread* aThread, TDes8& aBuffer) const;

   282     TInt SetConfigurationDescriptorTC(DThread* aThread, const TDes8& aBuffer);

   283     TInt GetOtgDescriptorTC(DThread* aThread, TDes8& aBuffer) const;

   284     TInt SetOtgDescriptor(const TDesC8& aBuffer);

   285     TInt GetInterfaceDescriptorTC(DThread* aThread, TDes8& aBuffer, TInt aInterface, TInt aSetting) const;

   286     TInt SetInterfaceDescriptor(const TDes8& aBuffer, TInt aInterface, TInt aSetting);

   287     TInt GetEndpointDescriptorTC(DThread* aThread, TDes8& aBuffer, TInt aInterface, TInt aSetting,

   288                                  TUint8 aEndpointAddress) const;

   289     TInt SetEndpointDescriptorTC(DThread* aThread, const TDes8& aBuffer, TInt aInterface, TInt aSetting,

   290                                  TUint8 aEndpointAddress);

   291     TInt GetEndpointDescriptorSize(TInt aInterface, TInt aSetting, TUint8 aEndpointAddress, TInt& aSize) const;

   292     TInt GetDeviceQualifierDescriptorTC(DThread* aThread, TDes8& aBuffer) const;

   293     TInt SetDeviceQualifierDescriptorTC(DThread* aThread, const TDes8& aBuffer);

   294     TInt GetOtherSpeedConfigurationDescriptorTC(DThread* aThread, TDes8& aBuffer) const;

   295     TInt SetOtherSpeedConfigurationDescriptorTC(DThread* aThread, const TDes8& aBuffer);

   296     TInt GetCSInterfaceDescriptorTC(DThread* aThread, TDes8& aBuffer, TInt aInterface, TInt aSetting) const;

   297     TInt SetCSInterfaceDescriptorTC(DThread* aThread, const TDes8& aBuffer, TInt aInterface, TInt aSetting,

   298                                     TInt aSize);

   299     TInt GetCSInterfaceDescriptorSize(TInt aInterface, TInt aSetting, TInt& aSize) const;

   300     TInt GetCSEndpointDescriptorTC(DThread* aThread, TDes8& aBuffer, TInt aInterface, TInt aSetting,

   301                                    TUint8 aEndpointAddress) const;

   302     TInt SetCSEndpointDescriptorTC(DThread* aThread, const TDes8& aBuffer, TInt aInterface, TInt aSetting,

   303                                    TUint8 aEndpointAddress, TInt aSize);

   304     TInt GetCSEndpointDescriptorSize(TInt aInterface, TInt aSetting, TUint8 aEndpointAddress, TInt& aSize) const;

   305 

   306     // String descriptors

   307     void SetIfcStringDescriptor(TUsbcStringDescriptor* aDesc, TInt aNumber, TInt aSetting=0);

   308     TInt GetStringDescriptorLangIdTC(DThread* aThread, TDes8& aLangId) const;

   309     TInt SetStringDescriptorLangId(TUint16 aLangId);

   310     TInt GetManufacturerStringDescriptorTC(DThread* aThread, TDes8& aString) const;

   311     TInt SetManufacturerStringDescriptorTC(DThread* aThread, const TDes8& aString);

   312     TInt RemoveManufacturerStringDescriptor();

   313     TInt GetProductStringDescriptorTC(DThread* aThread, TDes8& aString) const;

   314     TInt SetProductStringDescriptorTC(DThread* aThread, const TDes8& aString);

   315     TInt RemoveProductStringDescriptor();

   316     TInt GetSerialNumberStringDescriptorTC(DThread* aThread, TDes8& aString) const;

   317     TInt SetSerialNumberStringDescriptorTC(DThread* aThread, const TDes8& aString);

   318     TInt RemoveSerialNumberStringDescriptor();

   319     TInt GetConfigurationStringDescriptorTC(DThread* aThread, TDes8& aString) const;

   320     TInt SetConfigurationStringDescriptorTC(DThread* aThread, const TDes8& aString);

   321     TInt RemoveConfigurationStringDescriptor();

   322     TInt GetStringDescriptorTC(DThread* aThread, TInt aIndex, TDes8& aString) const;

   323     TInt SetStringDescriptorTC(DThread* aThread, TInt aIndex, const TDes8& aString);

   324     TInt RemoveStringDescriptor(TInt aIndex);

   325 

   326 private:

   327     // Descriptors

   328     void InsertIfcDesc(TUsbcDescriptorBase* aDesc);

   329     void InsertEpDesc(TUsbcDescriptorBase* aDesc);

   330     TInt FindIfcDescriptor(TInt aIfcNumber, TInt aIfcSetting) const;

   331     TInt FindEpDescriptor(TInt aIfcNumber, TInt aIfcSetting, TUint8 aEpAddress) const;

   332     void DeleteDescriptors(TInt aIndex, TInt aCount = 1);

   333     void UpdateConfigDescriptorLength(TInt aLength);

   334     void UpdateConfigDescriptorNumIfcs(TInt aNumber);

   335     void UpdateIfcNumbers(TInt aNumber);

   336     TInt GetDeviceDescriptor(TInt aIndex) const;

   337     TInt GetConfigurationDescriptor(TInt aIndex) const;

   338     TInt GetOtgDescriptor() const;

   339 

   340     // String descriptors

   341     TInt GetStringDescriptor(TInt aIndex) const;

   342     TInt GetDeviceStringDescriptorTC(DThread* aThread, TDes8& aString, TInt aIndex, TInt aPosition) const;

   343     TInt SetDeviceStringDescriptorTC(DThread* aThread, const TDes8& aString, TInt aIndex, TInt aPosition);

   344     TInt RemoveDeviceStringDescriptor(TInt aIndex, TInt aPosition);

   345     void ExchangeStringDescriptor(TInt aIndex, const TUsbcStringDescriptor* aDesc);

   346     TBool AnyStringDescriptors() const;

   347     TBool StringDescriptorExists(TInt aIndex) const;

   348     TInt FindAvailableStringPos() const;

   349 

   350 private:

   351     // Data members

   352     RPointerArray<TUsbcDescriptorBase> iDescriptors;

   353     RPointerArray<TUsbcStringDescriptorBase> iStrings;

   354     TInt iIfcIdx;

   355     TUint8* const iEp0_TxBuf;                                // points to the controller's ep0 TX buffer

   356     TBool iHighSpeed;                                        // true if currently operating at high-speed

   357     };

   358 

   359 

   360 #endif    // __USBCDESC_H__