sl@0: // Copyright (c) 1995-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of the License "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // e32/include/d32usbc.h sl@0: // User side class definitions for USB Device support. sl@0: // sl@0: // sl@0: sl@0: /** sl@0: @file d32usbc.h sl@0: @publishedPartner sl@0: @released sl@0: */ sl@0: sl@0: #ifndef __D32USBC_H__ sl@0: #define __D32USBC_H__ sl@0: sl@0: #include sl@0: #include sl@0: #include sl@0: sl@0: sl@0: sl@0: /** @internalComponent sl@0: */ sl@0: enum TTransferType sl@0: { sl@0: ETransferTypeReadData, sl@0: ETransferTypeReadPacket, sl@0: ETransferTypeWrite, sl@0: ETransferTypeNone, sl@0: ETransferTypeReadOneOrMore, sl@0: ETransferTypeReadUntilShort sl@0: }; sl@0: sl@0: sl@0: /** Available endpoints. At most only these are available per interface. sl@0: */ sl@0: enum TEndpointNumber sl@0: { sl@0: EEndpoint0 = 0, sl@0: EEndpoint1 = 1, sl@0: EEndpoint2 = 2, sl@0: EEndpoint3 = 3, sl@0: EEndpoint4 = 4, sl@0: EEndpoint5 = 5 sl@0: }; sl@0: sl@0: sl@0: sl@0: sl@0: /** Bandwidth indicators for an Interface sl@0: sl@0: @see RDevUsbcClient::SetInterface() sl@0: */ sl@0: enum TUsbcBandwidthPriority sl@0: { sl@0: /** Economical OUT buffering. */ sl@0: EUsbcBandwidthOUTDefault = 0x00, sl@0: /** More memory than Default for OUT buffering. */ sl@0: EUsbcBandwidthOUTPlus1 = 0x01, sl@0: /** More memory than Plus1 for OUT buffering. */ sl@0: EUsbcBandwidthOUTPlus2 = 0x02, sl@0: /** Maximum memory for OUT buffering. sl@0: Use this value for high volume USB High-speed sl@0: data transfers only, otherwise memory will be wasted. sl@0: */ sl@0: EUsbcBandwidthOUTMaximum = 0x03, sl@0: // sl@0: /** Economical IN buffering */ sl@0: EUsbcBandwidthINDefault = 0x00, sl@0: /** More memory than Default for IN buffering */ sl@0: EUsbcBandwidthINPlus1 = 0x10, sl@0: /** More memory than Plus1 for IN buffering */ sl@0: EUsbcBandwidthINPlus2 = 0x20, sl@0: /** Maximum memory for IN buffering. sl@0: Use this value for high volume USB High-speed sl@0: data transfers only, otherwise memory will be wasted. sl@0: */ sl@0: EUsbcBandwidthINMaximum = 0x30 sl@0: }; sl@0: sl@0: sl@0: sl@0: sl@0: sl@0: sl@0: sl@0: /** Bit positions of endpoints. sl@0: sl@0: @see RDevUsbcClient::EndpointStatusNotify() sl@0: @see RDevUsbcClient::EndpointTransferCancel() sl@0: sl@0: Bit position of endpoint0. sl@0: */ sl@0: const TUint KUsbcEndpoint0Bit = 1< TUsbcInterfaceInfoBuf; sl@0: sl@0: sl@0: /** The user side handle to the USB client driver. sl@0: */ sl@0: class RDevUsbcClient : public RBusLogicalChannel sl@0: { sl@0: public: sl@0: /** @internalComponent */ sl@0: enum TVer sl@0: { sl@0: EMajorVersionNumber = 0, sl@0: EMinorVersionNumber = 1, sl@0: EBuildVersionNumber = KE32BuildVersionNumber sl@0: }; sl@0: sl@0: enum TRequest sl@0: { sl@0: // Positive requests. sl@0: ERequestEp0 = 0x0, sl@0: ERequestEp1 = EEndpoint1, sl@0: ERequestEp2 = EEndpoint2, sl@0: ERequestEp3 = EEndpoint3, sl@0: ERequestEp4 = EEndpoint4, sl@0: ERequestEp5 = EEndpoint5, sl@0: ERequestUnused = 6, sl@0: ERequestAlternateDeviceStatusNotify = 7, sl@0: ERequestReEnumerate = 8, sl@0: ERequestEndpointStatusNotify = 9, sl@0: // The cancel TRequest's are interpreted as bitmaps. As they're not mixed sl@0: // with the previous ones, it doesn't matter if they have the same absolute sl@0: // value as those. sl@0: ERequestEp0Cancel = 1<(data), sizeof(data), sizeof(data)); sl@0: ret = usbPort.EndpointCaps(dataPtr); sl@0: @endcode sl@0: sl@0: @param aEpCapsBuf a descriptor encapsulating an array of TUsbcEndpointData. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt EndpointCaps(TDes8& aEpCapsBuf); sl@0: sl@0: /** Retrieves the capabilities of the USB device. sl@0: sl@0: @see TUsbDeviceCaps sl@0: sl@0: @param aDevCapsBuf a TUsbDeviceCaps object. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt DeviceCaps(TUsbDeviceCaps& aDevCapsBuf); sl@0: sl@0: /** Copies the current alternate setting for this interface into aInterfaceNumber sl@0: For USB Interfaces whose main interface is active, this will be 0 (zero). sl@0: sl@0: @param aInterfaceNumber current alternate setting for this interface is copied into this. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetAlternateSetting(TInt& aInterfaceNumber); sl@0: sl@0: /** Copies the current device status into aDeviceStatus. sl@0: sl@0: @param aDeviceStatus current device status is copied into this. sl@0: sl@0: @return KErrNone if successful sl@0: */ sl@0: inline TInt DeviceStatus(TUsbcDeviceState& aDeviceStatus); sl@0: sl@0: /** Copies the current endpoint status into aEndpointStatus. sl@0: sl@0: @param aEndpoint endpoint number valid for the current alternate setting. sl@0: @param aEndpointStatus the current endpoint status, might be stalled, not stalled or unknown. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt EndpointStatus(TEndpointNumber aEndpoint, TEndpointState& aEndpointStatus); sl@0: sl@0: /** Copies the number of bytes available in the aEndpoint read buffer into aNumberOfBytes. sl@0: sl@0: @param aEndpoint endpoint number valid for the current alternate setting. sl@0: @param aNumberOfBytes number of bytes available in the aEndpoint read buffer. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt QueryReceiveBuffer(TEndpointNumber aEndpoint, TInt& aNumberOfBytes); sl@0: sl@0: /** Requests that a zero length status packet be sent to the host in response sl@0: to a class or vendor specific ep0 SETUP packet. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SendEp0StatusPacket(); sl@0: sl@0: /** Stalls endpoint aEndpoint, usually to indicate an error condition with a previous command. sl@0: The host will normally send a SET_FEATURE command on ep0 to acknowledge and clear the stall. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt HaltEndpoint(TEndpointNumber aEndpoint); sl@0: sl@0: /** Clears the stall condition on endpoint aEndpoint. This is inluded for symmetry and test purposes. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt ClearHaltEndpoint(TEndpointNumber aEndpoint); sl@0: sl@0: /** Requests that device control be allocated to this channel. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetDeviceControl(); sl@0: sl@0: /** Relinquishes device control previously allocated to this channel. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt ReleaseDeviceControl(); sl@0: sl@0: /** Returns a bitmap of available ep0 maximum packet sizes. sl@0: sl@0: @return bitmap of available ep0 maximum packet sizes. sl@0: */ sl@0: inline TUint EndpointZeroMaxPacketSizes(); sl@0: sl@0: /** Requests that a maximum packet size of aMaxPacketSize be set on ep0. sl@0: sl@0: @param aMaxPacketSize The maximum packet size. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetEndpointZeroMaxPacketSize(TInt aMaxPacketSize); sl@0: sl@0: /** Queries the current maximum packet size on ep0. sl@0: sl@0: @return The currently set maximum packet size on ep0. sl@0: */ sl@0: inline TInt GetEndpointZeroMaxPacketSize(); sl@0: sl@0: /** Copies the current device descriptor into aDeviceDescriptor. sl@0: sl@0: @param aDeviceDescriptor Receives the current device descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetDeviceDescriptor(TDes8& aDeviceDescriptor); sl@0: sl@0: /** Sets the contents of aDeviceDescriptor to be the current device descriptor. sl@0: sl@0: @param aDeviceDescriptor contains the device descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetDeviceDescriptor(const TDesC8& aDeviceDescriptor); sl@0: sl@0: /** Gets the size of the current device descriptor. This is unlikely to be anything other than 9. sl@0: sl@0: @param aSize receives the size of the current device descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetDeviceDescriptorSize(TInt& aSize); sl@0: sl@0: /** Copies the current configuration descriptor into aConfigurationDescriptor. sl@0: sl@0: @param aConfigurationDescriptor Receives the current configuration descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetConfigurationDescriptor(TDes8& aConfigurationDescriptor); sl@0: sl@0: /** Sets the contents of aConfigurationDescriptor to be the current configuration descriptor. sl@0: sl@0: @param aConfigurationDescriptor contains the configuration descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetConfigurationDescriptor(const TDesC8& aConfigurationDescriptor); sl@0: sl@0: /** Gets the size of the current configuration descriptor. sl@0: sl@0: @param aSize receives the size of the current configuration descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetConfigurationDescriptorSize(TInt& aSize); sl@0: sl@0: /** Copies the interface descriptor into aInterfaceDescriptor for the interface with alternate sl@0: setting aSettingNumber, 0 for the main interface. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aInterfaceDescriptor Receives the interface descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetInterfaceDescriptor(TInt aSettingNumber, TDes8& aInterfaceDescriptor); sl@0: sl@0: /** Sets the interface descriptor contained in aInterfaceDescriptor for the interface with sl@0: alternate setting aSettingNumber, 0 for the main interface, for transmission to the host sl@0: during enumeration. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aInterfaceDescriptor Contains the interface descriptor to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetInterfaceDescriptor(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); sl@0: sl@0: /** Copies the size of the interface descriptor for the interface with alternate sl@0: setting aSettingNumber, 0 for the main interface, into aSize. sl@0: sl@0: @param aSettingNumber The alternate setting. sl@0: @param aSize receives the size of the interface descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetInterfaceDescriptorSize(TInt aSettingNumber, TInt& aSize); sl@0: sl@0: /** Copies the endpoint descriptor for logical endpoint number aEndpointNumber into aEndpointDescriptor sl@0: for the interface with alternate setting aSettingNumber, 0 for the main interface. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber. sl@0: @param aEndpointDescriptor Receives the endpoint descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, TDes8& aEndpointDescriptor); sl@0: sl@0: /** Sets the endpoint descriptor for logical endpoint number aEndpointNumber contained in sl@0: aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, sl@0: for transmission to the host during enumeration. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber Valid endpoint number on this interface. sl@0: @param aEndpointDescriptor Contains the endpoint descriptor to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, sl@0: const TDesC8& aEndpointDescriptor); sl@0: sl@0: /** Copies the size of the endpoint descriptor for logical endpoint number aEndpointNumber for the sl@0: interface with alternate setting aSettingNumber, 0 for the main interface, into aSize. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber Valid endpoint number on this interface. sl@0: @param aSize receives the size of the endpoint descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetEndpointDescriptorSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); sl@0: sl@0: /** Get OTG descriptor size sl@0: sl@0: @param aSize TInt reference which contains OTG descriptor size on return sl@0: */ sl@0: inline void GetOtgDescriptorSize(TInt& aSize); sl@0: sl@0: /** Get OTG descriptor of USB on-the-go feature sl@0: sl@0: @param aOtgDesc User-side buffer to store copy of descriptor sl@0: sl@0: @return KErrNone if successful sl@0: */ sl@0: inline TInt GetOtgDescriptor(TDes8& aOtgDesc); sl@0: sl@0: /** Set OTG descriptor by user to enable/disable USB on-the-go feature sl@0: sl@0: @param aOtgDesc Descriptor buffer containing OTG features sl@0: sl@0: @return KErrNone if successful sl@0: */ sl@0: inline TInt SetOtgDescriptor(const TDesC8& aOtgDesc); sl@0: sl@0: /** Copies the current device_qualifier descriptor into aDescriptor. sl@0: sl@0: @param aDescriptor Receives the current device_qualifier descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetDeviceQualifierDescriptor(TDes8& aDescriptor); sl@0: sl@0: /** Sets the device_qualifier descriptor to the contents of aDescriptor. sl@0: sl@0: @param aDescriptor contains the new device_qualifier descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetDeviceQualifierDescriptor(const TDesC8& aDescriptor); sl@0: sl@0: /** Copies the current other_speed_configuration descriptor into aDescriptor. sl@0: sl@0: @param aDescriptor Receives the current other_speed_configuration descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetOtherSpeedConfigurationDescriptor(TDes8& aDescriptor); sl@0: sl@0: /** Sets the other_speed_configuration descriptor to the contents of aDescriptor. sl@0: sl@0: @param aDescriptor contains the new other_speed_configuration descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetOtherSpeedConfigurationDescriptor(const TDesC8& aDescriptor); sl@0: sl@0: /** Copies the class specific interface descriptor block into aInterfaceDescriptor for the interface sl@0: with alternate setting aSettingNumber, 0 for the main interface. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aInterfaceDescriptor Contains the interface descriptor to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetCSInterfaceDescriptorBlock(TInt aSettingNumber, TDes8& aInterfaceDescriptor); sl@0: sl@0: /** aSettingNumber is the alternate interface setting, 0 for the main interface, that the descriptor block sl@0: aDes should be attached to. aDes is a block of data containing at least one class specific descriptor sl@0: for transmission during enumeration after the class interface descriptor (or alternate interface sl@0: descriptor) has been sent, but before the endpoint descriptors belonging to this interface are sent. sl@0: aDes may contain as many descriptors as are necessary or only 1. SetCSInterfaceDescriptorBlock() sl@0: should be called at any time after SetInterface() has been called to establish a main interface or an sl@0: alternate interface. More than one call may be made - the data blocks will be concatenated prior to sl@0: sending. No checking or validation of the contents of aDes will be made and it is the caller's sl@0: responsibility to ensure that the data supplied is correct and appropriate to the interface identified sl@0: by aSettingNumber. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aInterfaceDescriptor Contains the interface descriptor to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetCSInterfaceDescriptorBlock(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); sl@0: sl@0: /** Copies the size of the class specific interface descriptor block for the interface with alternate sl@0: setting aSettingNumber, 0 for the main interface, into aSize. sl@0: sl@0: @param aSettingNumber The alternate setting number. sl@0: @param aSize receives the size of the interface descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetCSInterfaceDescriptorBlockSize(TInt aSettingNumber, TInt& aSize); sl@0: sl@0: /** Copies the class specific endpoint descriptor for logical endpoint number aEndpointNumber sl@0: into aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main sl@0: interface. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber Valid endpoint number on this interface. sl@0: @param aEndpointDescriptor Receives the endpoint descriptor. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, sl@0: TDes8& aEndpointDescriptor); sl@0: sl@0: /** Sets the class specific endpoint descriptor for logical endpoint number aEndpointNumber contained in sl@0: aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, sl@0: for transmission to the host during enumeration. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber Valid endpoint number on this interface. sl@0: @param aEndpointDescriptor Contains the endpoint descriptor to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, sl@0: const TDesC8& aEndpointDescriptor); sl@0: sl@0: /** Copies the size of the class specific endpoint descriptor block for logical endpoint number sl@0: aEndpointNumber for the interface with alternate setting aSettingNumber, 0 for the main interface, sl@0: into aSize. sl@0: sl@0: @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. sl@0: @param aEndpointNumber Valid endpoint number on this interface. sl@0: @param aSize On return, contains the size of the class specific endpoint descriptor block. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt GetCSEndpointDescriptorBlockSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); sl@0: sl@0: /** Generates a Remote Wakeup bus condition sl@0: The capability of the device to generate Remote Wakeup signalling is enquired in sl@0: RDevUsbcClient::DeviceCaps. sl@0: sl@0: @return KErrNone if this signalling is possible and the signal has been generated. sl@0: */ sl@0: inline TInt SignalRemoteWakeup(); sl@0: sl@0: /** Simulates a physical removal of the USB cable by disabling the D+/- pull-ups.The iConnect member of sl@0: TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality is sl@0: supported. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt DeviceDisconnectFromHost(); sl@0: sl@0: /** Simulates a physical insertion of the USB cable by enabling the D+/- pull-ups.The iConnect member sl@0: of TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality sl@0: is supported. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt DeviceConnectToHost(); sl@0: sl@0: /** Powers up the UDC and connects it to the bus if one or more interfaces exist. sl@0: sl@0: @return KErrNone if UDC successfully powered up, KErrNotReady if no sl@0: interfaces have been registered yet, KErrHardwareNotAvailable if UDC sl@0: couldn't be activated. sl@0: */ sl@0: inline TInt PowerUpUdc(); sl@0: sl@0: /** Enquires about the current operating speed of the UDC. sl@0: sl@0: @return ETrue if the UDC is currently operating at High speed, EFalse otherwise. sl@0: */ sl@0: inline TBool CurrentlyUsingHighSpeed(); sl@0: sl@0: /** Allocates the use of aResource to aEndpoint. it will be used from when the current bus transfer has been sl@0: completed. sl@0: sl@0: @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint sl@0: behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. sl@0: @param aEndpoint The endpoint number to which the resource is to be allocated. sl@0: sl@0: @return KErrNone if successful, KErrInUse if the resource is already consumed and cannot be allocated, sl@0: KErrNotSupported if the endpoint does not support the resource requested. sl@0: sl@0: @publishedPartner @deprecated sl@0: sl@0: @see TUsbcEndpointInfo sl@0: */ sl@0: inline TInt AllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); sl@0: sl@0: /** Deallocates the use of aResource aEndpoint or ends a specified endpoint behaviour. sl@0: sl@0: @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint sl@0: behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. sl@0: @param aEndpoint The endpoint number from which the resource is to be removed. sl@0: sl@0: @return KErrNone if the resource has been successfully deallocated, KErrNotSupported if the endpoint sl@0: does not support the resource requested. sl@0: sl@0: @publishedPartner @deprecated sl@0: sl@0: @see TUsbcEndpointInfo sl@0: */ sl@0: inline TInt DeAllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); sl@0: sl@0: /** Queries endpoint resource use. sl@0: sl@0: @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint sl@0: behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. sl@0: @param aEndpoint The endpoint number at which the resource is to be queried. sl@0: sl@0: @return ETrue is the specified resource is in use at the endpoint and EFalse if not. sl@0: */ sl@0: inline TBool QueryEndpointResourceUse(TInt aEndpoint, TUsbcEndpointResource aResource); sl@0: sl@0: /** Request (i.e. claim for this channel) up to five endpoints and set the class type for this USB sl@0: interface. 'aInterfaceData' is a package buffer which describes the interface and all the endpoints sl@0: being requested by the driver for this interface. sl@0: sl@0: @param aInterfaceNumber Distinguishes between alternate interfaces. If these are not be used then this sl@0: should always be zero. If this parameter is used, then its value must be one more than that of the sl@0: proceeding alternate interface. sl@0: @param aInterfaceData a package buffer which describes the interface and all the endpoints being sl@0: requested by the driver for this interface. sl@0: @param aBandwidthPriority is a bitmap combining the required IN and OUT priorities. Values are in the sl@0: range [0,3] from the lowest priority bandwidth, 0, to the highest 3 and are separately specified for sl@0: IN and OUT endpoints. Interfaces requiring higher bandwidth are allocated significantly more buffering sl@0: than low bandwidth interfaces. Interfaces should not be given a higher bandwidth priority than they sl@0: require. sl@0: sl@0: @return KErrInUse if any of the endpoints being requested have already been claimed by another channel sl@0: KErrNotSupported if an endpoint with all of the specified properties is not supported on this sl@0: platform. KErrNoMemory if insufficient memory is available to complete the operation. sl@0: */ sl@0: inline TInt SetInterface(TInt aInterfaceNumber, TUsbcInterfaceInfoBuf& aInterfaceData, sl@0: TUint32 aBandwidthPriority = sl@0: (EUsbcBandwidthOUTDefault | EUsbcBandwidthINDefault)); sl@0: sl@0: /** Release an interface previously claimed by this channel. Alternate interfaces need to be released sl@0: in strict descending order, starting with the last (i.e. highest numbered) one. sl@0: It is not necessary to release an interface that wasn't successfully requested. sl@0: sl@0: @param aInterfaceNumber Specifies the alternate setting number 'aInterfaceNum' of the interface to be sl@0: released. sl@0: sl@0: @return KErrNone if successful. KErrArgument if the alternate setting doesn't exist or is released out sl@0: of order. sl@0: */ sl@0: inline TInt ReleaseInterface(TInt aInterfaceNumber); sl@0: sl@0: /** Copies the current string descriptor language ID (LANGID) code into the aLangId argument. Even though sl@0: the USB spec allows for the existence of a whole array of LANGID codes, we only support one. sl@0: sl@0: @param aLangId receives the LANGID code. sl@0: sl@0: @return KErrNone if successful, KErrArgument if problem with argument (memory cannot be written to, etc.). sl@0: */ sl@0: inline TInt GetStringDescriptorLangId(TUint16& aLangId); sl@0: sl@0: /** Sets the string descriptor language ID (LANGID). Even though the USB spec allows for the existence of sl@0: a whole array of LANGID codes, we only support one. sl@0: sl@0: @param aLangId the LANGID code to be set. sl@0: sl@0: @return KErrNone if successful. sl@0: */ sl@0: inline TInt SetStringDescriptorLangId(TUint16 aLangId); sl@0: sl@0: /** Copies the string descriptor identified by the iManufacturer index field of the Standard Device sl@0: Descriptor into the aString argument. sl@0: sl@0: @param aString receives manufacturer string. sl@0: sl@0: @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire sl@0: descriptor, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt GetManufacturerStringDescriptor(TDes16& aString); sl@0: sl@0: /** Sets the string descriptor identified by the iManufacturer index field of the Standard Device sl@0: Descriptor to the aString argument. sl@0: sl@0: @param aString Contains the new manufacturer string descriptor. sl@0: sl@0: @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from sl@0: aString (in which case the old string descriptor will be preserved). sl@0: */ sl@0: inline TInt SetManufacturerStringDescriptor(const TDesC16& aString); sl@0: sl@0: /** Removes (deletes) the string descriptor identified by the iManufacturer index field of the Standard sl@0: Device Descriptor and sets that field to zero. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt RemoveManufacturerStringDescriptor(); sl@0: sl@0: /** Retrieves the string descriptor identified by the iProduct index field of the Standard Device sl@0: Descriptor into the aString argument. sl@0: sl@0: @param aString receives product string. sl@0: sl@0: @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire sl@0: descriptor, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt GetProductStringDescriptor(TDes16& aString); sl@0: sl@0: /** Sets the string descriptor identified by the iProduct index field of the Standard Device Descriptor to sl@0: the aString argument. sl@0: sl@0: @param aString Contains the new product string descriptor. sl@0: sl@0: @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from sl@0: aString (in which case the old string descriptor will be preserved). sl@0: */ sl@0: inline TInt SetProductStringDescriptor(const TDesC16& aString); sl@0: sl@0: /** Removes (deletes) the string descriptor identified by the iProduct index field of the Standard Device sl@0: Descriptor and sets that field to zero. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt RemoveProductStringDescriptor(); sl@0: sl@0: /** Retrieves the string descriptor identified by the iSerialNumber index field of the Standard Device sl@0: Descriptor into the aString argument. sl@0: sl@0: @param aString receives product string. sl@0: sl@0: @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire sl@0: descriptor, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt GetSerialNumberStringDescriptor(TDes16& aString); sl@0: sl@0: /** Sets the string descriptor identified by the iSerialNumber index field of the Standard Device sl@0: Descriptor to the aString argument. sl@0: sl@0: @param aString Contains the new serial number string descriptor. sl@0: sl@0: @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from sl@0: aString (in which case the old string descriptor will be preserved). sl@0: */ sl@0: inline TInt SetSerialNumberStringDescriptor(const TDesC16& aString); sl@0: sl@0: /** Removes (deletes) the string descriptor identified by the iSerialNumber index field of the Standard sl@0: Device Descriptor and sets that field to zero. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt RemoveSerialNumberStringDescriptor(); sl@0: sl@0: /** Retrieves the string descriptor identified by the iConfiguration index field of the (first) Standard sl@0: Configuration Descriptor into the aString argument. sl@0: sl@0: @param aString receives configuration string. sl@0: sl@0: @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire sl@0: descriptor, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt GetConfigurationStringDescriptor(TDes16& aString); sl@0: sl@0: /** Sets the string descriptor identified by the iConfiguration index field of the Standard Configuration sl@0: Descriptor to the aString argument. sl@0: sl@0: @param aString Contains the new serial number string descriptor. sl@0: sl@0: @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from sl@0: aString (in which case the old string descriptor will be preserved). sl@0: */ sl@0: inline TInt SetConfigurationStringDescriptor(const TDesC16& aString); sl@0: sl@0: /** Removes (deletes) the string descriptor identified by the iConfiguration index field of the Standard sl@0: Configuration Descriptor and sets that field to zero. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. sl@0: */ sl@0: inline TInt RemoveConfigurationStringDescriptor(); sl@0: sl@0: /** Copies the string of the USB string descriptor at the specified index in the string descriptor array sl@0: into the aString argument. sl@0: sl@0: Although this function can also be used for it, for querying most standard string descriptors sl@0: there exists a set of dedicated access functions. sl@0: sl@0: @see RDevUsbcClient::GetStringDescriptorLangId sl@0: @see RDevUsbcClient::GetManufacturerStringDescriptor sl@0: @see RDevUsbcClient::GetProductStringDescriptor sl@0: @see RDevUsbcClient::GetSerialNumberStringDescriptor sl@0: @see RDevUsbcClient::GetConfigurationStringDescriptor sl@0: sl@0: @param aIndex The position of the string descriptor in the string descriptor array. sl@0: @param aString The target location for the string descriptor copy. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index, sl@0: KErrArgument if MaxLength() of aString is too small to hold the entire descriptor. sl@0: */ sl@0: inline TInt GetStringDescriptor(TUint8 aIndex, TDes16& aString); sl@0: sl@0: /** Sets the aString argument to be the string of a USB string descriptor at the specified index in the sl@0: string descriptor array. If a string descriptor already exists at that position then its string will sl@0: be replaced. sl@0: sl@0: Care should be taken, when choosing aIndex, not to inadvertently overwrite one of the standard sl@0: string descriptors. For their manipulation there exists a set of dedicated access functions. sl@0: sl@0: @see RDevUsbcClient::SetStringDescriptorLangId sl@0: @see RDevUsbcClient::SetManufacturerStringDescriptor sl@0: @see RDevUsbcClient::SetProductStringDescriptor sl@0: @see RDevUsbcClient::SetSerialNumberStringDescriptor sl@0: @see RDevUsbcClient::SetConfigurationStringDescriptor sl@0: sl@0: @param aIndex The position of the string descriptor in the string descriptor array. sl@0: @param aString Contains the string descriptor to be set. sl@0: sl@0: @return KErrNone if successful, KErrArgument if aIndex is invalid, KErrNoMemory if no memory sl@0: is available to store the new string (an existing descriptor at that index will be preserved). sl@0: */ sl@0: inline TInt SetStringDescriptor(TUint8 aIndex, const TDesC16& aString); sl@0: sl@0: /** Removes (deletes) the USB string descriptor at the specified index in the string descriptor array. sl@0: The position in the array of other string descriptors is not affected. sl@0: sl@0: Care should be taken, when choosing aIndex, not to inadvertently delete a standard string descriptor sl@0: (also because index references from non-string descriptors would be invalidated). For the deletion sl@0: of most standard string descriptors there exists a set of dedicated functions. sl@0: sl@0: @see RDevUsbcClient::RemoveManufacturerStringDescriptor sl@0: @see RDevUsbcClient::RemoveProductStringDescriptor sl@0: @see RDevUsbcClient::RemoveSerialNumberStringDescriptor sl@0: @see RDevUsbcClient::RemoveConfigurationStringDescriptor sl@0: sl@0: @param aIndex The position of the string descriptor in the string descriptor array. sl@0: sl@0: @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index. sl@0: */ sl@0: inline TInt RemoveStringDescriptor(TUint8 aIndex); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. sl@0: Request completes when the specified number of bytes is received, length taken from max. length of sl@0: descriptor. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: */ sl@0: inline void Read(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. sl@0: Request completes when the specified number of bytes is received. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: @param aLen The number of bytes to read. sl@0: */ sl@0: inline void Read(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); sl@0: sl@0: /** Asynchronously read an entire packet of data from endpoint 'aEndpoint' into the descriptor 'aDes'. sl@0: If a packet has previously been partly read. then only the remainder of the packet will be returned. sl@0: The request should be for the maximum packet size of the endpoint. If less data is requested, then sl@0: after this read completes the remainder of the data in the packet will be discarded and the next read sl@0: will start from the next available packet. sl@0: Request completes when either a complete packet is received or the length of the packet currently sl@0: being received exceeds 'aMaxLen'. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: @param aMaxLen . sl@0: */ sl@0: inline void ReadPacket(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aMaxLen); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. sl@0: Request completes when the specified number of bytes is received (in first version, sl@0: length taken from max. length of descriptor). sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: */ sl@0: inline void ReadUntilShort(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. sl@0: Request completes when the specified number of bytes is received (in first version, sl@0: length taken from max. length of descriptor). sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: @param aLen The number of bytes to receive. sl@0: */ sl@0: inline void ReadUntilShort(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. The request completes sl@0: when the specified number of bytes is received, length taken from max. length of descriptor or a sl@0: packet whose size is smaller than the endpoint's maximum packet size is received. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: */ sl@0: inline void ReadOneOrMore(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes); sl@0: sl@0: /** Asynchronously read data from endpoint 'aEndpoint' into the descriptor 'aDes'. The request completes sl@0: when the specified number of bytes is received, or a packet whose size is smaller than the endpoint's sl@0: maximum packet size is received. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to read from. sl@0: @param aDes Descriptor to receive the data. sl@0: @param aLen The number of bytes to receive. sl@0: */ sl@0: inline void ReadOneOrMore(TRequestStatus& aStatus, TEndpointNumber aEndpoint, TDes8& aDes, TInt aLen); sl@0: sl@0: /** Cancels an outstanding read request. The request will complete with whatever data is available. sl@0: */ sl@0: inline void ReadCancel(TEndpointNumber aEndpoint); sl@0: sl@0: /** Asynchronously write 'aLen' bytes of data to endpoint 'aEndpoint' from descriptor 'aDes'. 'aZlpRequired' sl@0: (optional) signals that ZLP termination may be required. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpoint The endpoint number to write to. sl@0: @param aDes Descriptor to provide the data. sl@0: @param aLen The number of bytes of data to be written. sl@0: @param aZlpRequired True, if ZLP termination is required; false, otherwise. sl@0: */ sl@0: inline void Write(TRequestStatus& aStatus, TEndpointNumber aEndpoint, const TDesC8& aDes, TInt aLen, sl@0: TBool aZlpRequired=EFalse); sl@0: sl@0: /** Cancels an outstanding write request on endpoint aEndpoint. sl@0: sl@0: @param aEndpoint The endpoint number whose write is to be cancelled. sl@0: */ sl@0: inline void WriteCancel(TEndpointNumber aEndpoint); sl@0: sl@0: /** Cancels any transfer on any endpoint specified in aEndpointMask. sl@0: sl@0: @code sl@0: // Cancel transfer requests on endpoints 1, 2 & 3 sl@0: usbPort.EndpointTransferCancel(KUsbcEndpoint1Bit | KUsbcEndpoint2Bit | KUsbcEndpoint3Bit); sl@0: @endcode sl@0: sl@0: @param aEndpointMask bitmap of the endpoints. sl@0: */ sl@0: inline void EndpointTransferCancel(TUint aEndpointMask); sl@0: sl@0: /** Register for notification when a change of the Interface alternate setting or the USB Controller's sl@0: current state occurs. When the alternate setting or the Controller state changes, then the sl@0: asynchronous function completes and the current alternate setting number or Controller state is sl@0: written back to aValue. If the KUsbAlternateSetting bit is set then the remaining bits are the sl@0: alternate setting number. Otherwise aValue is interpreted as a TUsbcDeviceState. sl@0: sl@0: @see TUsbcDeviceState sl@0: sl@0: @param aStatus The request status. sl@0: @param aValue Receives the alternate setting number or Controller state. sl@0: */ sl@0: inline void AlternateDeviceStatusNotify(TRequestStatus& aStatus, TUint& aValue); sl@0: sl@0: /** Completes an AlternateDeviceStatusNotify request. If a request has previously been made then the sl@0: status variable is updated with the current device state. sl@0: */ sl@0: inline void AlternateDeviceStatusNotifyCancel(); sl@0: sl@0: /** If the channel has changed the grouping of endpoints between interfaces or changed the interface class sl@0: type from the defaults then it is necessary to force a re-enumeration. This will typically involve the sl@0: Symbian OS device initiating a disconnection and re-connection. This is an asynchronous operation sl@0: which will complete when the Controller is successfully configured by the host, i.e. has achieved sl@0: EUsbcDeviceStateConfigured. Since it is not known if the operation has failed, at the same time that sl@0: a ReEnumerate request is made, a timer should be set up to complete after approximately 5 seconds. It sl@0: can be assumed that if the operation has not completed after this time interval then it will not sl@0: complete. sl@0: sl@0: @param aStatus The request status. sl@0: */ sl@0: inline void ReEnumerate(TRequestStatus& aStatus); sl@0: sl@0: /** Cancels an outstanding ReEnumerate() request. sl@0: */ sl@0: inline void ReEnumerateCancel(); sl@0: sl@0: /** Register for notification when a change in stall status of any of the interface's endpoints occurs, sl@0: but not ep0. When a change in stall status occurs, then the asynchronous function completes and the sl@0: current stall state is written back to 'aEndpointStatus' as a bit map: Only stall state changes caused sl@0: by SET_FEATURE and CLEAR_FEATURE standard commands on ep0 will be notified when this function sl@0: completes. After this request completes the request should be re-issued to obtain future sl@0: notifications. sl@0: sl@0: @param aStatus The request status. sl@0: @param aEndpointMask a bitmap of the endpoints stall status. This is filled in when the call completes sl@0: bit 1 represents the interface's virtual endpoint 1, (KUsbcEndpoint1Bit) sl@0: bit 2 represents the interface's virtual endpoint 2, (KUsbcEndpoint2Bit) etc. sl@0: bit value 0 - not stalled, sl@0: bit value 1 - stalled. sl@0: */ sl@0: inline void EndpointStatusNotify(TRequestStatus& aStatus, TUint& aEndpointMask); sl@0: sl@0: /** Completes an endpoint status notify request. sl@0: */ sl@0: inline void EndpointStatusNotifyCancel(); sl@0: sl@0: /** Get current on-the-go features relating to the ability of device/host pair to sl@0: perform OTG role swap. sl@0: sl@0: @param aFeatures On return it contanis features the device currently has sl@0: bit 2 represents b_hnp_enable, (KUsbOtgAttr_B_HnpEnable) sl@0: bit 3 represents a_hnp_support, (KUsbOtgAttr_A_HnpSupport) sl@0: bit 4 represents a_alt_hnp_support, (KUsbOtgAttr_A_AltHnpSupport) sl@0: @return KErrNone if successful, KErrNotSupported if OTG is not supported by sl@0: this device, otherwise system-wide error returns sl@0: */ sl@0: inline TInt GetOtgFeatures(TUint8& aFeatures); sl@0: sl@0: /** Register for notification on USB on-the-go features' change. If any OTG feature sl@0: is changed, request completes and current feature value is filled in aValue. sl@0: sl@0: @param aStatus Request status object sl@0: @param aValue On request completion, it contains current OTG feature value sl@0: */ sl@0: inline void OtgFeaturesNotify(TRequestStatus& aStatus, TUint8& aValue); sl@0: sl@0: /** Cancel pending OTG feature request. sl@0: */ sl@0: inline void OtgFeaturesNotifyCancel(); sl@0: sl@0: #endif // #ifndef __KERNEL_MODE__ sl@0: }; sl@0: sl@0: sl@0: #include sl@0: sl@0: sl@0: #endif // __D32USBC_H__