diff -r d3e8e7d462dd -r f92a4f87e424 usbdrv/peripheral/public/d32usbcsc.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/usbdrv/peripheral/public/d32usbcsc.h Tue Aug 31 17:01:47 2010 +0300 @@ -0,0 +1,1558 @@ +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// e32\include\d32usbcsc.h +// User side class definitions for USB Device support. +// +// + +/** + @file d32usbcsc.h + @publishedPartner + @released +*/ + +#ifndef __D32USBCSC_H__ +#define __D32USBCSC_H__ + +#include +#include +#include + + +/** This means that SetInterface was called after RealizeInterface had been called. + RealizeInterface is meant to signal that all interfaces have been set. +*/ +const TInt KErrUsbAlreadyRealized = -6813; //Changed from -6713 for future compatibility with the d32usbcshared.h file + +const TInt KErrAlternateSettingChanged = -6814; + + +const TUint KChunkCellSize = 1; //1 32 bit integer +const TInt KEpDescPacketSizeOffset = 4; + +/** The user side enpoint number of Endpoint Zero. */ +const TInt KEp0Number = 0; + +/* Used in TUsbcScHdrEndpointRecord to describe the endpoint type +*/ + +const TUint8 KUsbScHdrEpDirectionIn=1; +const TUint8 KUsbScHdrEpDirectionOut=2; +const TUint8 KUsbScHdrEpDirectionBiDir=3; + + +const TUint8 KUsbScHdrEpTypeControl = 0; +const TUint8 KUsbScHdrEpTypeIsochronous =1; +const TUint8 KUsbScHdrEpTypeBulk = 2; +const TUint8 KUsbScHdrEpTypeInterrupt = 3; +const TUint8 KUsbScHdrEpTypeUnknown = ~0; +/** Used in the the Shared Chunk Header, to represent an endpoint. +*/ +class TUsbcScHdrEndpointRecord + { +public: + inline TUsbcScHdrEndpointRecord(TInt aBufferNo, TUint8 aType); + inline TUint Direction() const; + inline TUint Type() const; +public: + TUint8 iBufferNo; + TUint8 iType; + TUint16 iReserved; + }; + + +// This is used to hold the geometry of the shared buffers +class TUsbcScBufferRecord + { + friend class DLddUsbcScChannel; + +public: + inline TUint Offset() const; + inline TUint Size() const; +private: + inline void Set(TUint aOffset, TUint aEndOffset); + TUint iOffset; + TUint iSize; + }; + +struct SUsbcScBufferHeader + { + TInt iHead; // Where the LDD will next write a transfer + TInt iTail; // Indicates the fist packet that user side is processing (anything prior is disposable) + TInt iBilTail; // This is not used by LDD at all, but just for the BIL's benifit. + }; + + +struct SUsbcScAlternateSetting + { + TUint16 iSetting; + TUint16 iSequence; + }; + +/** Endpoint pair information. This can be used to control pairing of endpoint +for classes that require explicit pairing of endpoint, such as ADC. + +This is currently not used. +*/ + +class TEndpointPairInfo +{ +public: + TEndpointPairInfo(TUint8 aType=0, TUint16 aPair=0, TUint8 aSpare=0); +public: + TUint8 iType; + TUint8 iSpare; + TUint16 iPair; +}; + +/** +This is the buffer number reserved for use with endpoint zero with the ReadDataNotify and WriteData methods. +*/ +const TInt KUsbcScEndpointZero = -1; + +/** +This flag is reserved in TUsbcscEndpointInfo::iFlags, to indicate that the client driver's client wishes reads to operate in a coupled fashion. +This behaviour is not currently supported. +*/ +const TUint KUsbScCoupledRead = 0x1; + +/** +This flag, used in parameter aFlag of WriteData, is used to indicate that a ZLP should be sent. +*/ +const TUint KUsbcScWriteFlagsZlp = 0x0001; + + +// Bit fields used in iFlags of TUsbcScTransferHeader + +const TUint KUsbcScShortPacket = 0x0001; +const TUint KUsbcScStateChange = 0x0004; + +class TUsbcScTransferHeader +{ +public: +#ifdef _DEBUG + TUint iHashId; + TUint iSequence; +#endif + TUint iBytes; + TUint iFlags; + TUint iNext; + TUint16 iAltSettingSeq; + TInt16 iAltSetting; + union + { + TUint i[1]; // Extends + TUint8 b[4]; // Extends + } iData; +}; + +/** The desired endpoint capabilities used in RDevUsbcScClient::SetInterface(). + +This derived class has additional fields used in the shared chunk USB driver. +*/ +class TUsbcScEndpointInfo: public TUsbcEndpointInfo + { +public: + TUsbcScEndpointInfo(TUint aType=UsbShai::KUsbEpTypeBulk, TUint aDir=UsbShai::KUsbEpDirOut, TInt aInterval=0, TInt aExtra=0, + TUint aBufferSize=0, TUint aReadSize=0); + + +public: + /** This indicates the requested size of the endpoint buffer and must be at + least as large as iReadSize. + */ + TUint iBufferSize; + + /** This is the amount of data that the LDD reads from the bus before it sets + up another read and is normally intended to read many packets. + */ + TUint iReadSize; + + /** TEndpointPairInfo represents pairing information for isochronous endpoints. + Should be zero in other cases. If this specifies paired endpoints then + iExtra (in the base class TUsbcEndpointInfo) also needs to be set to the + class specific size for this endpoint descriptor (This is here only for future use). + */ + TEndpointPairInfo iPairing; + + /** The necessary alignment, in bytes, that needs to be applied to the transfer start points + of the data. This is only observed on OUT endpoints. Zero can be specified to indicate + there are no class side requirements for alignment. The alignment for OUT endpoints is + which ever is greater of this field or the USB hardware requirements. + */ + TUint iAlignment; + + /** Flags to indicate how the endpoint should function. None currently defined, + but could be used to allow support for direct read. + */ + TUint iFlags; + + /** Reserved for future use. */ + TUint32 iReserved2[2]; + }; + +/** This must be filled in prior to a call to RDevUsbcClient::SetInterface(). +*/ +class TUsbcScInterfaceInfo + { +public: + TUsbcScInterfaceInfo(TInt aClass=0, TInt aSubClass=0, TInt aProtocol=0, + TDesC16* aString=NULL, TUint aTotalEndpoints=0); +public: + /** The class, subclass and protocol that this interface supports. */ + TUsbcClassInfo iClass; + /** The description string for the interface. Used to construct the interface string descriptor. */ + const TDesC16* iString; + /** Total number of endpoints being requested (0-5). Endpoint 0 should not be included in this number. */ + TUint iTotalEndpointsUsed; + /** Desired properties of the endpoints requested. + Do NOT include endpoint 0. + APIs use endpoint numbers that are offsets into this array. + */ + TUsbcScEndpointInfo iEndpointData[KMaxEndpointsPerClient]; + /** 32 flag bits used for specifying miscellaneous Interface features. + Currently defined are: + - KUsbcInterfaceInfo_NoEp0RequestsPlease = 0x00000001 + */ + TUint32 iFeatureWord; + }; + +/** Package buffer for a TUsbcInterfaceInfo object. + + @see TUsbcInterfaceInfo +*/ +typedef TPckgBuf TUsbcScInterfaceInfoBuf; + +struct TUsbcScChunkHdrOffs + { + TUint iBuffers; + TUint iAltSettings; + }; + + +class TUsbcScChunkBuffersHeader // Not instantiable + { + friend class DLddUsbcScChannel; + friend class TRealizeInfo; + +public: + inline TUsbcScBufferRecord* Ep0Out() const; + inline TUsbcScBufferRecord* Ep0In() const; + inline TUsbcScBufferRecord* Buffers(TInt aBuffer) const; + inline TInt NumberOfBuffers() const; + +private: + TUsbcScChunkBuffersHeader(); +private: + TInt iRecordSize; + TInt iNumOfBufs; + TUint8 iBufferOffset[8]; // Extends + }; + +struct TUsbcScChunkAltSettingHeader // Not instantiable + { + TInt iEpRecordSize; + TInt iNumOfAltSettings; + TUint iAltTableOffset[1]; // Extends + }; + +class TEndpointBuffer; + + +/** The user side handle to the USB client driver. +*/ +class RDevUsbcScClient : public RBusLogicalChannel + { +public: + /** @internalComponent */ + enum TVer + { + EMajorVersionNumber = 0, + EMinorVersionNumber = 1, + EBuildVersionNumber = KE32BuildVersionNumber + }; + +// Bit pattern. s = Request/Control. c = Cancel, m = mode bits, B = Buffer number, R = request number. +// scmm mmmm | mmmm mmmm | mmBB BBBB |RRRR RRRR + + enum TRequest + { + ERequestWriteData = 1, + ERequestReadDataNotify = 2, + ERequestAlternateDeviceStatusNotify = 3, + ERequestReEnumerate = 4, + ERequestEndpointStatusNotify = 5, + ERequestOtgFeaturesNotify = 6, + ERequestMaxRequests, // 7 + + ERequestCancel = 0x40000000, + + ERequestWriteDataCancel = ERequestWriteData | ERequestCancel, + ERequestReadDataNotifyCancel = ERequestReadDataNotify | ERequestCancel, + ERequestAlternateDeviceStatusNotifyCancel = ERequestAlternateDeviceStatusNotify | ERequestCancel, + ERequestReEnumerateCancel = ERequestReEnumerate | ERequestCancel, + ERequestEndpointStatusNotifyCancel = ERequestEndpointStatusNotify | ERequestCancel, + ERequestOtgFeaturesNotifyCancel = ERequestOtgFeaturesNotify | ERequestCancel + }; + + enum TControl + { + // Changing the order of these enums will break BC. + EControlEndpointZeroRequestError, // 00 + EControlEndpointCaps, + EControlDeviceCaps, + EControlGetAlternateSetting, + EControlDeviceStatus, + EControlEndpointStatus, + EControlSetInterface, + EControlReleaseInterface, + EControlSendEp0StatusPacket, + EControlHaltEndpoint, // 09 + // + EControlClearHaltEndpoint, // 10 + EControlSetDeviceControl, + EControlReleaseDeviceControl, + EControlEndpointZeroMaxPacketSizes, + EControlSetEndpointZeroMaxPacketSize, + EControlGetDeviceDescriptor, + EControlSetDeviceDescriptor, + EControlGetDeviceDescriptorSize, + EControlGetConfigurationDescriptor, + EControlSetConfigurationDescriptor, // 19 + // + EControlGetConfigurationDescriptorSize, // 20 + EControlGetInterfaceDescriptor, + EControlSetInterfaceDescriptor, + EControlGetInterfaceDescriptorSize, + EControlGetEndpointDescriptor, + EControlSetEndpointDescriptor, + EControlGetEndpointDescriptorSize, + EControlGetCSInterfaceDescriptor, + EControlSetCSInterfaceDescriptor, + EControlGetCSInterfaceDescriptorSize, // 29 + // + EControlGetCSEndpointDescriptor, // 30 + EControlSetCSEndpointDescriptor, + EControlGetCSEndpointDescriptorSize, + EControlSignalRemoteWakeup, + EControlGetStringDescriptorLangId, + EControlSetStringDescriptorLangId, + EControlGetManufacturerStringDescriptor, + EControlSetManufacturerStringDescriptor, + EControlRemoveManufacturerStringDescriptor, + EControlGetProductStringDescriptor, // 39 + // + EControlSetProductStringDescriptor, // 40 + EControlRemoveProductStringDescriptor, + EControlGetSerialNumberStringDescriptor, + EControlSetSerialNumberStringDescriptor, + EControlRemoveSerialNumberStringDescriptor, + EControlGetConfigurationStringDescriptor, + EControlSetConfigurationStringDescriptor, + EControlRemoveConfigurationStringDescriptor, + EControlDeviceDisconnectFromHost, + EControlDeviceConnectToHost, // 49 + // + EControlDevicePowerUpUdc, // 50 + EControlDumpRegisters, + EControlAllocateEndpointResource, + EControlDeAllocateEndpointResource, + EControlQueryEndpointResourceUse, + EControlGetEndpointZeroMaxPacketSize, + EControlGetDeviceQualifierDescriptor, + EControlSetDeviceQualifierDescriptor, + EControlGetOtherSpeedConfigurationDescriptor, + EControlSetOtherSpeedConfigurationDescriptor, // 59 + // + EControlCurrentlyUsingHighSpeed, // 60 + EControlSetStringDescriptor, + EControlGetStringDescriptor, + EControlRemoveStringDescriptor, + EControlSetOtgDescriptor, + EControlGetOtgDescriptor, + EControlGetOtgFeatures, + EControlRealizeInterface, + EControlStartNextInAlternateSetting + }; + + + // const static TUint KFieldIdPos = 0; + const static TUint KFieldIdMask = 0xFF; + const static TUint KFieldBuffPos = 8; + const static TUint KFieldBuffMask = 0x3F; + const static TUint KFieldFlagsPos = 14; + const static TUint KFieldFlagsMask = 0xFFFF; + + +public: + +#ifndef __KERNEL_MODE__ + + /** Opens a channel. + + @param aUnit This should be 0 (zero). + + @return KErrNone if successful. + */ + inline TInt Open(TInt aUnit); + + inline TVersion VersionRequired() const; + + /** Stalls ep0 to signal command fault to the host. + + @return KErrNone if successful. + */ + inline TInt EndpointZeroRequestError(); + + /** Retrieves the capabilities of all the endpoints on the device. + + Suggested use is as follows: + + @code + TUsbcEndpointData data[KUsbcMaxEndpoints]; + TPtr8 dataPtr(reinterpret_cast(data), sizeof(data), sizeof(data)); + ret = usbPort.EndpointCaps(dataPtr); + @endcode + + @param aEpCapsBuf A descriptor encapsulating an array of TUsbcEndpointData. + + @return KErrNone if successful. + */ + inline TInt EndpointCaps(TDes8& aEpCapsBuf); + + /** Retrieves the capabilities of the USB device. + + @see TUsbDeviceCaps + + @param aDevCapsBuf A TUsbDeviceCaps object. + + @return KErrNone if successful. + */ + inline TInt DeviceCaps(TUsbDeviceCaps& aDevCapsBuf); + + /** Copies the current alternate setting for this interface into aInterfaceNumber + For USB Interfaces whose main interface is active, this will be 0 (zero). + + @param aInterfaceNumber Current alternate setting for this interface is copied into this. + + @return KErrNone if successful. + */ + inline TInt GetAlternateSetting(TInt& aInterfaceNumber); + + /** Copies the current device status into aDeviceStatus. + + @param aDeviceStatus Current device status is copied into this. + + @return KErrNone if successful + */ + inline TInt DeviceStatus(TUsbcDeviceState& aDeviceStatus); + + /** Copies the current endpoint status into aEndpointStatus. + + @param aEndpoint Endpoint number valid for the current alternate setting. + @param aEndpointStatus The current endpoint status, might be stalled, not stalled or unknown. + + @return KErrNone if successful. + */ + inline TInt EndpointStatus(TInt aEndpoint, TEndpointState& aEndpointStatus); + + + /** Requests that a zero length status packet be sent to the host in response + to a class or vendor specific ep0 SETUP packet. + + @return KErrNone if successful. + */ + inline TInt SendEp0StatusPacket(); + + /** Stalls endpoint aEndpoint, usually to indicate an error condition with a previous command. + The host will normally send a SET_FEATURE command on ep0 to acknowledge and clear the stall. + + @return KErrNone if successful. + */ + inline TInt HaltEndpoint(TInt aEndpoint); + + /** Clears the stall condition on endpoint aEndpoint. This is inluded for symmetry and test purposes. + + @return KErrNone if successful. + */ + inline TInt ClearHaltEndpoint(TInt aEndpoint); + + /** Requests that device control be allocated to this channel. + + @return KErrNone if successful. + */ + inline TInt SetDeviceControl(); + + /** Relinquishes device control previously allocated to this channel. + + @return KErrNone if successful. + */ + inline TInt ReleaseDeviceControl(); + + /** Returns a bitmap of available ep0 maximum packet sizes. + + @return bitmap of available ep0 maximum packet sizes. + */ + inline TUint EndpointZeroMaxPacketSizes(); + + /** Requests that a maximum packet size of aMaxPacketSize be set on ep0. + + @param aMaxPacketSize The maximum packet size. + + @return KErrNone if successful. + */ + inline TInt SetEndpointZeroMaxPacketSize(TInt aMaxPacketSize); + + /** Queries the current maximum packet size on ep0. + + @return The currently set maximum packet size on ep0. + */ + inline TInt GetEndpointZeroMaxPacketSize(); + + /** Copies the current device descriptor into aDeviceDescriptor. + + @param aDeviceDescriptor Receives the current device descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceDescriptor(TDes8& aDeviceDescriptor); + + /** Sets the contents of aDeviceDescriptor to be the current device descriptor. + + @param aDeviceDescriptor Contains the device descriptor. + + @return KErrNone if successful. + */ + inline TInt SetDeviceDescriptor(const TDesC8& aDeviceDescriptor); + + /** Gets the size of the current device descriptor. This is unlikely to be anything other than 9. + + @param aSize Receives the size of the current device descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceDescriptorSize(TInt& aSize); + + /** Copies the current configuration descriptor into aConfigurationDescriptor. + + @param aConfigurationDescriptor Receives the current configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetConfigurationDescriptor(TDes8& aConfigurationDescriptor); + + /** Sets the contents of aConfigurationDescriptor to be the current configuration descriptor. + + @param aConfigurationDescriptor Contains the configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt SetConfigurationDescriptor(const TDesC8& aConfigurationDescriptor); + + /** Gets the size of the current configuration descriptor. + + @param aSize Receives the size of the current configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetConfigurationDescriptorSize(TInt& aSize); + + /** Copies the interface descriptor into aInterfaceDescriptor for the interface with alternate + setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Receives the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetInterfaceDescriptor(TInt aSettingNumber, TDes8& aInterfaceDescriptor); + + /** Sets the interface descriptor contained in aInterfaceDescriptor for the interface with + alternate setting aSettingNumber, 0 for the main interface, for transmission to the host + during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetInterfaceDescriptor(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); + + /** Copies the size of the interface descriptor for the interface with alternate + setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber The alternate setting. + @param aSize receives the size of the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetInterfaceDescriptorSize(TInt aSettingNumber, TInt& aSize); + + /** Copies the endpoint descriptor for logical endpoint number aEndpointNumber into aEndpointDescriptor + for the interface with alternate setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber The endpoint number of the endpoint. + @param aEndpointDescriptor Receives the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, TDes8& aEndpointDescriptor); + + /** Sets the endpoint descriptor for logical endpoint number aEndpointNumber contained in + aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, + for transmission to the host during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Contains the endpoint descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetEndpointDescriptor(TInt aSettingNumber, TInt aEndpointNumber, + const TDesC8& aEndpointDescriptor); + + /** Copies the size of the endpoint descriptor for logical endpoint number aEndpointNumber for the + interface with alternate setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aSize Receives the size of the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetEndpointDescriptorSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); + + /** Get OTG descriptor size + + @param aSize TInt Reference which contains OTG descriptor size on return. + */ + inline void GetOtgDescriptorSize(TInt& aSize); + + /** Get OTG descriptor of USB on-the-go feature. + + @param aOtgDesc User-side buffer to store copy of descriptor. + + @return KErrNone if successful. + */ + inline TInt GetOtgDescriptor(TDes8& aOtgDesc); + + /** Set OTG descriptor by user to enable/disable USB on-the-go feature. + + @param aOtgDesc Descriptor buffer containing OTG features. + + @return KErrNone if successful. + */ + inline TInt SetOtgDescriptor(const TDesC8& aOtgDesc); + + /** Copies the current device_qualifier descriptor into aDescriptor. + + @param aDescriptor Receives the current device_qualifier descriptor. + + @return KErrNone if successful. + */ + inline TInt GetDeviceQualifierDescriptor(TDes8& aDescriptor); + + /** Sets the device_qualifier descriptor to the contents of aDescriptor. + + @param aDescriptor Contains the new device_qualifier descriptor. + + @return KErrNone if successful. + */ + inline TInt SetDeviceQualifierDescriptor(const TDesC8& aDescriptor); + + /** Copies the current other_speed_configuration descriptor into aDescriptor. + + @param aDescriptor Receives the current other_speed_configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt GetOtherSpeedConfigurationDescriptor(TDes8& aDescriptor); + + /** Sets the other_speed_configuration descriptor to the contents of aDescriptor. + + @param aDescriptor Contains the new other_speed_configuration descriptor. + + @return KErrNone if successful. + */ + inline TInt SetOtherSpeedConfigurationDescriptor(const TDesC8& aDescriptor); + + /** Copies the class specific interface descriptor block into aInterfaceDescriptor for the interface + with alternate setting aSettingNumber, 0 for the main interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt GetCSInterfaceDescriptorBlock(TInt aSettingNumber, TDes8& aInterfaceDescriptor); + + /** aSettingNumber is the alternate interface setting, 0 for the main interface, that the descriptor block + aDes should be attached to. aDes is a block of data containing at least one class specific descriptor + for transmission during enumeration after the class interface descriptor (or alternate interface + descriptor) has been sent, but before the endpoint descriptors belonging to this interface are sent. + aDes may contain as many descriptors as are necessary or only one. SetCSInterfaceDescriptorBlock() + should be called at any time after SetInterface() has been called to establish a main interface or an + alternate interface. More than one call may be made - the data blocks will be concatenated prior to + sending. No checking or validation of the contents of aDes will be made and it is the caller's + responsibility to ensure that the data supplied is correct and appropriate to the interface identified + by aSettingNumber. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aInterfaceDescriptor Contains the interface descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetCSInterfaceDescriptorBlock(TInt aSettingNumber, const TDesC8& aInterfaceDescriptor); + + /** Copies the size of the class specific interface descriptor block for the interface with alternate + setting aSettingNumber, 0 for the main interface, into aSize. + + @param aSettingNumber The alternate setting number. + @param aSize receives the size of the interface descriptor. + + @return KErrNone if successful. + */ + inline TInt GetCSInterfaceDescriptorBlockSize(TInt aSettingNumber, TInt& aSize); + + /** Copies the class specific endpoint descriptor for logical endpoint number aEndpointNumber + into aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main + interface. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Receives the endpoint descriptor. + + @return KErrNone if successful. + */ + inline TInt GetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, + TDes8& aEndpointDescriptor); + + /** Sets the class specific endpoint descriptor for logical endpoint number aEndpointNumber contained in + aEndpointDescriptor for the interface with alternate setting aSettingNumber, 0 for the main interface, + for transmission to the host during enumeration. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aEndpointDescriptor Contains the endpoint descriptor to be set. + + @return KErrNone if successful. + */ + inline TInt SetCSEndpointDescriptorBlock(TInt aSettingNumber, TInt aEndpointNumber, + const TDesC8& aEndpointDescriptor); + + /** Copies the size of the class specific endpoint descriptor block for logical endpoint number + aEndpointNumber for the interface with alternate setting aSettingNumber, 0 for the main interface, + into aSize. + + @param aSettingNumber Alternate setting number on the interface, 0 for the main interface. + @param aEndpointNumber Valid endpoint number on this interface. + @param aSize On return, contains the size of the class specific endpoint descriptor block. + + @return KErrNone if successful. + */ + inline TInt GetCSEndpointDescriptorBlockSize(TInt aSettingNumber, TInt aEndpointNumber, TInt& aSize); + + /** Generates a Remote Wakeup bus condition. + The capability of the device to generate Remote Wakeup signalling is enquired in + RDevUsbcClient::DeviceCaps. + + @return KErrNone if this signalling is possible and the signal has been generated. + */ + inline TInt SignalRemoteWakeup(); + + /** Simulates a physical removal of the USB cable by disabling the D+/- pull-ups.The iConnect member of + TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality is + supported. + + @return KErrNone if successful. + */ + inline TInt DeviceDisconnectFromHost(); + + /** Simulates a physical insertion of the USB cable by enabling the D+/- pull-ups.The iConnect member + of TUsbDeviceCapsV01, returned by RDevUsbcClient::DeviceCaps(), indicates whether this functionality + is supported. + + @return KErrNone if successful. + */ + inline TInt DeviceConnectToHost(); + + /** Powers up the UDC and connects it to the bus if one or more interfaces exist. + + @return KErrNone if UDC successfully powered up, KErrNotReady if no + interfaces have been registered yet, KErrHardwareNotAvailable if UDC + couldn't be activated. + */ + inline TInt PowerUpUdc(); + + /** Enquires about the current operating speed of the UDC. + + @return ETrue if the UDC is currently operating at High speed, EFalse otherwise. + */ + inline TBool CurrentlyUsingHighSpeed(); + + /** Allocates the use of aResource to aEndpoint. It will be used from when the current bus transfer has been + completed. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number to which the resource is to be allocated. + + @return KErrNone if successful, KErrInUse if the resource is already consumed and cannot be allocated, + KErrNotSupported if the endpoint does not support the resource requested. + + @publishedPartner @deprecated + */ + inline TInt AllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Deallocates the use of aResource aEndpoint or ends a specified endpoint behaviour. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number from which the resource is to be removed. + + @return KErrNone if the resource has been successfully deallocated, KErrNotSupported if the endpoint + does not support the resource requested. + + @publishedPartner @deprecated + */ + inline TInt DeAllocateEndpointResource(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Queries endpoint resource use. + + @param aResource is typically some rationed hardware resource or possibly specifies a type of endpoint + behaviour. aResource is not a bitmap and TEndpointResource values should not be combined. + @param aEndpoint The endpoint number at which the resource is to be queried. + + @return ETrue is the specified resource is in use at the endpoint and EFalse if not. + */ + inline TBool QueryEndpointResourceUse(TInt aEndpoint, TUsbcEndpointResource aResource); + + /** Request (i.e. claim for this channel) up to five endpoints and set the class type for this USB + interface. 'aInterfaceData' is a package buffer which describes the interface and all the endpoints + being requested by the driver for this interface. + + @param aInterfaceNumber Distinguishes between alternate interfaces. If these are not be used then this + should always be zero. If this parameter is used, then its value must be one more than that of the + proceeding alternate interface. + @param aInterfaceData A package buffer which describes the interface and all the endpoints being + requested by the driver for this interface. + + + @return KErrInUse if any of the endpoints being requested have already been claimed by another channel. + KErrNotSupported if an endpoint with all of the specified properties is not supported on this + platform. KErrNoMemory if insufficient memory is available to complete the operation. + */ + inline TInt SetInterface(TInt aInterfaceNumber, TUsbcScInterfaceInfoBuf& aInterfaceData); + + + /** + This method should be called after SetInterface has been called for all possible alternative settings. + Calling this invalidates further calls to SetInterface. On success, a chunk handle is created and + passed back though aChunk. This is needed for the user side to access the shared chunk where the + data is stored. Note that if you are using the BIL (described later), then FinalizeInterface (...) + should be used instead, which will call this method. + + @return KErrNone on successful completion, or one of the system wide error codes. + */ + inline TInt RealizeInterface(RChunk& aChunk); + + + /** Release an interface previously claimed by this channel. Alternate interfaces need to be released + in strict descending order, starting with the last (i.e. highest numbered) one. + It is not necessary to release an interface that wasn't successfully requested. + + @param aInterfaceNumber Specifies the alternate setting number 'aInterfaceNum' of the interface to be + released. + + @return KErrNone if successful. KErrArgument if the alternate setting doesn't exist or is released out + of order. + */ + inline TInt ReleaseInterface(TInt aInterfaceNumber); + + /** Copies the current string descriptor language ID (LANGID) code into the aLangId argument. Even though + the USB spec allows for the existence of a whole array of LANGID codes, we only support one. + + @param aLangId Receives the LANGID code. + + @return KErrNone if successful, KErrArgument if problem with argument (memory cannot be written to, etc.). + */ + inline TInt GetStringDescriptorLangId(TUint16& aLangId); + + /** Sets the string descriptor language ID (LANGID). Even though the USB spec allows for the existence of + a whole array of LANGID codes, we only support one. + + @param aLangId The LANGID code to be set. + + @return KErrNone if successful. + */ + inline TInt SetStringDescriptorLangId(TUint16 aLangId); + + /** Copies the string descriptor identified by the iManufacturer index field of the Standard Device + Descriptor into the aString argument. + + @param aString Receives manufacturer string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetManufacturerStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iManufacturer index field of the Standard Device + Descriptor to the aString argument. + + @param aString Contains the new manufacturer string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetManufacturerStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iManufacturer index field of the Standard + Device Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveManufacturerStringDescriptor(); + + /** Retrieves the string descriptor identified by the iProduct index field of the Standard Device + Descriptor into the aString argument. + + @param aString Receives product string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetProductStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iProduct index field of the Standard Device Descriptor to + the aString argument. + + @param aString Contains the new product string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetProductStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iProduct index field of the Standard Device + Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveProductStringDescriptor(); + + /** Retrieves the string descriptor identified by the iSerialNumber index field of the Standard Device + Descriptor into the aString argument. + + @param aString Receives product string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetSerialNumberStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iSerialNumber index field of the Standard Device + Descriptor to the aString argument. + + @param aString Contains the new serial number string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetSerialNumberStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iSerialNumber index field of the Standard + Device Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveSerialNumberStringDescriptor(); + + /** Retrieves the string descriptor identified by the iConfiguration index field of the (first) Standard + Configuration Descriptor into the aString argument. + + @param aString Receives configuration string. + + @return KErrNone if successful, KErrArgument if MaxLength of aString is too small to hold the entire + descriptor, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt GetConfigurationStringDescriptor(TDes16& aString); + + /** Sets the string descriptor identified by the iConfiguration index field of the Standard Configuration + Descriptor to the aString argument. + + @param aString Contains the new serial number string descriptor. + + @return KErrNone if successful, KErrNoMemory if no memory is available to store the new string from + aString (in which case the old string descriptor will be preserved). + */ + inline TInt SetConfigurationStringDescriptor(const TDesC16& aString); + + /** Removes (deletes) the string descriptor identified by the iConfiguration index field of the Standard + Configuration Descriptor and sets that field to zero. + + @return KErrNone if successful, KErrNotFound if the string descriptor couldn't be found. + */ + inline TInt RemoveConfigurationStringDescriptor(); + + /** Copies the string of the USB string descriptor at the specified index in the string descriptor array + into the aString argument. + + Although this function can also be used for it, for querying most standard string descriptors + there exists a set of dedicated access functions. + + @see RDevUsbcClient::GetStringDescriptorLangId + @see RDevUsbcClient::GetManufacturerStringDescriptor + @see RDevUsbcClient::GetProductStringDescriptor + @see RDevUsbcClient::GetSerialNumberStringDescriptor + @see RDevUsbcClient::GetConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + @param aString The target location for the string descriptor copy. + + @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index, + KErrArgument if MaxLength() of aString is too small to hold the entire descriptor. + */ + inline TInt GetStringDescriptor(TUint8 aIndex, TDes16& aString); + + /** Sets the aString argument to be the string of a USB string descriptor at the specified index in the + string descriptor array. If a string descriptor already exists at that position then its string will + be replaced. + + Care should be taken, when choosing aIndex, not to inadvertently overwrite one of the standard + string descriptors. For their manipulation there exists a set of dedicated access functions. + + @see RDevUsbcClient::SetStringDescriptorLangId + @see RDevUsbcClient::SetManufacturerStringDescriptor + @see RDevUsbcClient::SetProductStringDescriptor + @see RDevUsbcClient::SetSerialNumberStringDescriptor + @see RDevUsbcClient::SetConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + @param aString Contains the string descriptor to be set. + + @return KErrNone if successful, KErrArgument if aIndex is invalid, KErrNoMemory if no memory + is available to store the new string (an existing descriptor at that index will be preserved). + */ + inline TInt SetStringDescriptor(TUint8 aIndex, const TDesC16& aString); + + /** Removes (deletes) the USB string descriptor at the specified index in the string descriptor array. + The position in the array of other string descriptors is not affected. + + Care should be taken, when choosing aIndex, not to inadvertently delete a standard string descriptor + (also because index references from non-string descriptors would be invalidated). For the deletion + of most standard string descriptors there exists a set of dedicated functions. + + @see RDevUsbcClient::RemoveManufacturerStringDescriptor + @see RDevUsbcClient::RemoveProductStringDescriptor + @see RDevUsbcClient::RemoveSerialNumberStringDescriptor + @see RDevUsbcClient::RemoveConfigurationStringDescriptor + + @param aIndex The position of the string descriptor in the string descriptor array. + + @return KErrNone if successful, KErrNotFound if no string descriptor exists at the specified index. + */ + inline TInt RemoveStringDescriptor(TUint8 aIndex); + + + + /** Requests notification for when there is data available on the buffer indicated. If the buffer + already has data in it, it will return immediately, otherwise it will block until there is. + + If the BIL methods are being used (recommended), then this method should not be called directly, + using TEndpointBuffer::GetBuffer instead. + + @param aBufferNumber Indicates the buffer for which the caller wishes to know about data + additions. The buffer needed of any given endpoint can be found by inspecting the alternative + setting table, in the chunk header. The location of the buffer can be found by looking at the + buffer offset table, also in the chunk header. + + @param aStatus The request status where notification of completion is directed. KErrCancel is + returned if the asynchronous operation was cancelled. + + @param aLength A preference for the quantity of data to be read. This value is only a + suggestion and my be ignored. The default value of 0 indicates no preference. + + @return KErrNone on success, or KErrArgument if the buffer number is invalid. + */ + inline TInt ReadDataNotify(TInt aBufferNumber, TRequestStatus& aStatus, TInt aLength=0); + + + /** Requests the LDD to write the contents of the given buffer to the USB hardware. Notification is + given when this is complete. More then one write request can be queued on any one endpoint, to allow + for less Hardware idling between buffers. + + If the BIL methods are being used (recommended), then this method should not be called directly, + using TEndpointBuffer::WriteBuffer instead. + + @param aBufferNumber represents the buffer number of the buffer of which the caller has placed the + data. As described with ReadDataNotify(...), details of the buffers can be found in the chunk header. + + @param aStart Represents the start offset of the data within the chunk. This start location must be + aligned to a multiple of the maximum packet size for the endpoint, so that the data can be DMAed + straight out of the buffer. + + @param aLength Represents the amount of data to be sent to the host in bytes. + + @param aFlags Is a bitfield, where bit 0 should be set if a ZLP is to be sent to the host after the + current transaction. All other bits are reserved for future use. +*/ + inline void WriteData(TInt aBufferNumber, TUint aStart, TUint aLength, TUint aFlags, TRequestStatus& aStatus); + + + + /** Cancels an outstanding read request on endpoint buffer aBufferNumber. + + @param aBufferNumber The endpoint buffer number whose read is to be cancelled. + */ + inline void ReadCancel(TInt aBufferNumber); + + + /** Cancels an outstanding write request on endpoint buffer aBufferNumber. + + @param aBufferNumber The endpoint buffer number whose write is to be cancelled. + */ + inline void WriteCancel(TInt aBufferNumber); + + /** Cancels any transfer on any endpoint buffer specified in aBufferMask. + + @code + // Cancel transfer requests on buffers 1, 2, 3 & 4 + usbPort.EndpointTransferCancel(1 | 2 | 4 | 8); + @endcode + + @param aBufferMask bitmap of the endpoint buffer numbers. + */ + inline void EndpointTransferCancel(TUint aBufferMask); + + /** Register for notification when a change of the Interface alternate setting or the USB Controller's + current state occurs. When the alternate setting or the Controller state changes, then the + asynchronous function completes and the current alternate setting number or Controller state is + written back to aValue. If the KUsbAlternateSetting bit is set then the remaining bits are the + alternate setting number. Otherwise aValue is interpreted as a TUsbcDeviceState. + + @see TUsbcDeviceState + + @param aStatus The request status. + @param aValue Receives the alternate setting number or Controller state. + */ + inline void AlternateDeviceStatusNotify(TRequestStatus& aStatus, TUint& aValue); + + /** Completes an AlternateDeviceStatusNotify request. If a request has previously been made then the + status variable is updated with the current device state. + */ + inline void AlternateDeviceStatusNotifyCancel(); + + /** If the channel has changed the grouping of endpoints between interfaces or changed the interface class + type from the defaults then it is necessary to force a re-enumeration. This will typically involve the + Symbian OS device initiating a disconnection and re-connection. This is an asynchronous operation + which will complete when the Controller is successfully configured by the host, i.e. has achieved + UsbShai::EUsbPeripheralStateConfigured. Since it is not known if the operation has failed, at the same time that + a ReEnumerate request is made, a timer should be set up to complete after approximately 5 seconds. It + can be assumed that if the operation has not completed after this time interval then it will not + complete. + + @param aStatus The request status. + */ + inline void ReEnumerate(TRequestStatus& aStatus); + + /** Cancels an outstanding ReEnumerate() request. + */ + inline void ReEnumerateCancel(); + + /** Register for notification when a change in stall status of any of the interface's endpoints occurs, + but not ep0. When a change in stall status occurs, then the asynchronous function completes and the + current stall state is written back to 'aEndpointStatus' as a bit map: Only stall state changes caused + by SET_FEATURE and CLEAR_FEATURE standard commands on ep0 will be notified when this function + completes. After this request completes the request should be re-issued to obtain future + notifications. + + @param aStatus The request status. + @param aEndpointMask A bitmap of the endpoints' stall status. This is filled in when the call completes. + bit 1 represents the interface's virtual endpoint 1, (KUsbcEndpoint1Bit) + bit 2 represents the interface's virtual endpoint 2, (KUsbcEndpoint2Bit) etc. + bit value 0 - not stalled, + bit value 1 - stalled. + */ + inline void EndpointStatusNotify(TRequestStatus& aStatus, TUint& aEndpointMask); + + /** Completes an endpoint status notify request. + */ + inline void EndpointStatusNotifyCancel(); + + /** Get current on-the-go features relating to the ability of device/host pair to + perform OTG role swap. + + @param aFeatures On return it contains features the device currently has. + bit 2 represents b_hnp_enable, (KUsbOtgAttr_B_HnpEnable) + bit 3 represents a_hnp_support, (KUsbOtgAttr_A_HnpSupport) + bit 4 represents a_alt_hnp_support, (KUsbOtgAttr_A_AltHnpSupport) + @return KErrNone if successful, KErrNotSupported if OTG is not supported by + this device, otherwise system-wide error returns. + */ + inline TInt GetOtgFeatures(TUint8& aFeatures); + + /** Register for notification on USB on-the-go features' change. If any OTG feature + is changed, request completes and current feature value is filled in aValue. + + @param aStatus Request status object. + @param aValue On request completion, contains current OTG feature value. + */ + inline void OtgFeaturesNotify(TRequestStatus& aStatus, TUint8& aValue); + + /** Cancel pending OTG feature request. + */ + inline void OtgFeaturesNotifyCancel(); + + /** This function retrieves the alternate setting that the WriteData function can + write to. After a host sets the alternate setting, writes to the IN endpoint + are not permitted by the LDD until this method has been called. + This function is not asynchronous nor blocking, and should not be used to + detect that an alternate setting has happened. + + If the BIL methods are being used (recommended), then this method should not be called directly. + + @return The alternative setting number or KErrInUse if the current alternative + setting is already in use, that is to say that the alternative setting has not changed. + */ + inline TInt StartNextInAlternateSetting(); + + + /*******************************\ + * Buffer Interface Layer (BIL) * + \*******************************/ + + // This following functions, as well as the ones in TEndpointBuffer (below), + // can be considered the BIL. + + + /** + Finalize the interface, creating a chunk for use with reading/writing to endpoints. + FinalizeInterface should be called after all alternate interfaces have been set up with SetInteface. + Any attempt to call SetInterface after this stage will fail. + + @return KErrNone if operation is successfull + System wide error codes if chunk creation failed + */ + IMPORT_C TInt FinalizeInterface(); + + /** + Finalize the interface, creating a chunk for use with reading/writing to endpoints. This + version of the method provides a handle to the chunk, which is needed if the + buffer is to be passed and used by other processes. + FinalizeInterface should be called after all alternate interfaces have been set up with SetInteface. + Any attempt to call SetInterface after this stage will fail. + + @param aChunk On success aChunk points to the created chunk. + @return KErrNone if operation is successfull + System wide error codes if chunk creation failed + */ + IMPORT_C TInt FinalizeInterface(RChunk*& aChunk); + + /** + Opens an endpoint, an endpoint should be opened before any operations are attempted on it. + + @param aEpB On success aEpB will be filled with the relevant details for that endpoint + @param aEpI endpoint number to be opened + @return KErrNone if operation is successfull + KErrNotFound if endpoint number is not valid for current alternate setting + KErrInUse if endpoint is already opened + KErrArgument if endpoint buffer argument passed is already in existence and being used + */ + IMPORT_C TInt OpenEndpoint(TEndpointBuffer & aEpB, TInt aEpI); + + /** + Switches to processing from one Alternate setting to the next. All open endpoints (except EP0) must + be close before this can be called. + + @param aFlush If ETrue, the method will purge the buffers of any data unread for the old setting. + If each endpoint was not read up until KErrEof was reached, then this should be set. + + @return the alternate Setting if operation is successful + KErrInUse if any endpoints in present alternate setting is still open (except Ep0) + KErrNotReady if there is no change in alternate setting + KErrInUse if StartNextInAlternateSetting detects no change in alternate setting. + KErrCorrupt if the buffer structure becomes corrupt. + */ + IMPORT_C TInt StartNextOutAlternateSetting(TBool aFlush); + + /** + Sets aChunk to RChunk currently in use by BIL. + + @param aChunk aChunk will point to RChunk currently in use by BIL + @return KErrNone on success otherwise a system wide error code, if an error has occurred. + */ + IMPORT_C TInt GetDataTransferChunk(RChunk*& aChunk); + +private: + /** @internalTechnology */ + TInt Drain(TUint aBuffer); + /** @internalTechnology */ + TInt Peek(TUint aBuffer); + /** @internalTechnology */ + TInt FindNextAlternateSetting(); + +private: + TUint8 iEndpointStatus; /** @internalTechnology Each bit corresponds to each endpoint's open/close status. */ + RChunk iSharedChunk; /** @internalTechnology The shared chunk in use. */ + TInt iAltSettingSeq; /** @internalTechnology Used to track alternate setting changes. */ + TInt iAlternateSetting; /** @internalTechnology The alternate setting used by OUT endpoints, which may lag that of IN endpoints. */ + TInt iNewAltSetting; /** @internalTechnology Used to track the next alternate setting change on OUT endpoints, + during transition from one to the next. */ + TInt iInAltSetting; /** @internalTechnology The alternate setting used by IN endpoints, which may be ahead of OUT endpoints. */ + + + friend class TEndpointBuffer; +#endif // #ifndef __KERNEL_MODE__ + }; + +#ifndef __KERNEL_MODE__ + + +/** + This class forms part of the Buffer Interface Layer (BIL), which forms the + user side component of the USB Shared Chunk Client. Objects of this type + represent the shared chunk buffer, for a given endpoint. + The method RDevUsbcScClient::OpenEndpoint() should be used to initialise + objects of this type. +*/ +class TEndpointBuffer + { +public: + + /** + This return value used by GetBuffer indicates that the item pointed to by + aBuffer/aOffset represents a state change, instead of endpoint data. + */ + const static TInt KStateChange = 0x01; + +public: + IMPORT_C TEndpointBuffer(); + + /** + Read the next block of data from the Shared chunk buffer. This method should be used if the user wishes to process one block of data at a time. + This method also expires the previously read block, meaning that the memory used by the block of data may be re-used by the system, overwriting it + with new data. + @param aBuffer aBuffer will point to data location in shared chunk + @param aSize aSize will hold the number of valid bytes that can be read + @param aZLP aZLP will indicate whether its a short packet or not + @param aStatus In case of no data available to be read, aStatus will be passed on to LDD, and user side should wait for + asynchronous call ReadDataNotify to return + @param aLength Not used at the moment + @return KErrCompletion if operation is successfull and data is available in the buffer + KErrNone if no data is available to be read + KErrEof if alternate setting has changed + KErrAccessDenied if endpoint is not opened + KErrNotSupported if its an IN endpoint + TEndpointBuffer::KStateChange if the returned data represents a state change (Ep0 only) + */ + IMPORT_C TInt GetBuffer(TAny*& aBuffer,TUint& aSize,TBool& aZLP,TRequestStatus& aStatus,TUint aLength=0); + + /** + Read the next block of data from the Shared chunk buffer. This method should be used if the user wishes to process one block of data at a time. + This method also expires the previously read block, meaning that the memory used by the block of data may be re-used by the system, overwriting it + with new data. + @param aOffset aOffset will point to data offset in shared chunk + @param aSize aSize will hold the number of valid bytes that can be read + @param aZLP aZLP will indicate whether its a short packet or not + @param aStatus In case of no data available to be read, aStatus will be passed on to LDD, and user side should wait for + asynchronous call ReadDataNotify to return + @param aLength Not used at the moment + @return KErrCompletion if operation is successfull and data is available in the buffer + KErrNone if no data is available to be read + KErrEof if alternate setting has changed + KErrAccessDenied if endpoint is not opened + KErrNotSupported if its an IN endpoint + TEndpointBuffer::KStateChange if the returned data represents a state change (Ep0 only) + */ + inline TInt GetBuffer(TUint& aOffset,TUint& aSize,TBool& aZLP,TRequestStatus& aStatus,TUint aLength=0); + + /** + Read the next block of data from the Shared chunk buffer. This method should be used if the user wishes to process more than one block of data + simultaneously. The user must call one of the Expire() methods to free the memory used by the block of data, and make it available for new data. + @param aBuffer aBuffer will point to data location in shared chunk + @param aSize aSize will hold the number of valid bytes that can be read + @param aZLP aZLP will indicate whether its a short packet or not + @param aStatus In case of no data available to be read, aStatus will be passed on to LDD, and user side should wait for + asynchronous call ReadDataNotify to return + @param aLength Not used at the moment + @return KErrCompletion if operation is successfull and data is available in the buffer + KErrNone if no data is available to be read + KErrEof if alternate setting has changed + KErrAccessDenied if endpoint is not opened + KErrNotSupported if its an IN endpoint + TEndpointBuffer::KStateChange if the returned data represents a state change (Ep0 only) + */ + IMPORT_C TInt TakeBuffer(TAny*& aBuffer,TUint& aSize,TBool& aZLP,TRequestStatus& aStatus,TUint aLength=0); + + /** + Used in conjunction with TakeBuffer method. This will make the 'oldest' block of data previously read out using the TakeBuffer method, but not + already expired, to be released back to the system. This block can then be overwritten with new data, when it becomes available. + @return KErrNotSupported if its an IN endpoint + KErrNone if iTail is successfully bumped to the next transfer to be read + */ + + IMPORT_C TInt Expire(); + + /** + Used in conjunction with TakeBuffer method. This function allows blocks to be expired in a different order from which the user read the data out + of the buffer. Note that the system will only reuse blocks up to the point of the oldest non-expired block read. This means that the user must + ensure to expire all blocks in a timely manner to prevent the system from running out of usable memory. + @param aAddress aAddress is the start address of the block of data previously read by the user which can be overwritten. + @return KErrNotSupported if its an IN endpoint + KErrNone if iTail is successfully bumped to the next transfer to be read + KErrNotFound if a 'transfer' with start address of the data block is aAddress is not found + */ + + IMPORT_C TInt Expire(TAny* aAddress); + + /** + Initiates write operation. + @param aBuffer aBuffer will point to data in shared chunk to be written out. aBuffer should be aligned + @param aSize aSize will hold the number of valid bytes to be written out + @param aZLP aZLP will indicate whether a ZLP should be transmitted after writing the data out + @param aStatus This is an asynchronous function and user side should wait on status to know the end of write operation + @return KErrNone if a write is successfully queued + KErrEof if an alternate setting change has occurred, ending this endpoint. + KErrNotSupported if its an OUT endpoint + KErrAccessDenied if endpoint is not opened, or if buffer is out of range + */ + IMPORT_C TInt WriteBuffer(TAny* aBuffer,TUint aSize,TBool aZLP,TRequestStatus& aStatus); + + /** + Initiates write operation. + @param aOffset aOffset will point to offset of data in shared chunk to be written out. + @param aSize aSize will hold the number of valid bytes to be written out + @param aZLP aZLP will indicate whether a ZLP should be transmitted after writing the data out + @param aStatus This is an asynchronous function and user side should wait on status to know the end of write operation + @return KErrNone if a write is successfully queued + KErrEof if an alternate setting change has occurred, ending this endpoint. + KErrNotSupported if its an OUT endpoint + KErrAccessDenied if endpoint is not opened, or if buffer is out of range + */ + IMPORT_C TInt WriteBuffer(TUint aOffset,TUint aSize,TBool aZLP,TRequestStatus& aStatus); + /** + For IN endpoints, this method retrieves the geometry for the buffer, for which the + caller should stay within, when using the WriteBuffer method. + + @param aStart A pointer, which is set to point to the start of the buffer. + @param aSize An TUint for which the size (in bytes) of buffer, is written into. + + @returns KErrNotSupported if the object is on an open IN endpoint, + otherwise it KErrNone is returned on success. + */ + IMPORT_C TInt GetInBufferRange(TAny*& aStart, TUint& aSize); + + /** + For IN endpoints, this method retrieves the geometry for the buffer, for which the + caller should stay within, when using the WriteBuffer method. + + @param aStart A TUint for which the buffer's start offset from the start of the chunk, + in written into. + @param aSize An TUint for which the size (in bytes) of buffer, is written into. + + @returns KErrNotSupported if the object is on an open IN endpoint, + otherwise it KErrNone is returned on success. + */ + IMPORT_C TInt GetInBufferRange(TUint& aStart, TUint& aSize); + + /** + This method closes the endpoint, after it was opened with + RDevUsbcScClient::OpenEndpoint(...). + No method of this object can be used after this call, until + RDevUsbcScClient::OpenEndpoint(...) is called on it again. + + @return KErrNone on success, otherwise KErrNotFound, if the current object is not open. + */ + IMPORT_C TInt Close(); + + IMPORT_C void Dump(); + + /** + Used to retrieve the endpoint number for which this object was open on. + + @returns the endpoint number opened by this object. + */ + inline TInt GetEndpointNumber(); + +private: + /** @internalTechnology */ + void Construct(RDevUsbcScClient* aClient, TUint8* aBaseAddr, const TUsbcScHdrEndpointRecord* aEpType, + TInt aEndpointNumber, SUsbcScBufferHeader* aEndpointHdr=NULL); + +private: + enum TDir {EValid = KErrNone, ENotValid = KErrNotSupported, EEOF = KErrEof}; + TDir iInState; /** @internalTechnology describes state of endpoint, KErrNone if IN endpoint and ready to use, KErrNotSupportd if not an IN endpoint, KErrEof on alternate setting change */ + TDir iOutState; /** @internalTechnology describes state of endpoint, KErrNone if OUT endpoint and ready to use, KErrNotSupportd if not an OUT endpoint, KErrEoF on alternate setting change */ + TInt iEndpointNumber; /** @internalTechnology associated endpoint number */ + TInt iBufferNum; /** @internalTechnology buffer number within shared chunk */ + RDevUsbcScClient *iClient; /** @internalTechnology Parent RDevUsbcScClient object */ + TUint iBaseAddr; /** @internalTechnology The address of the beginning of the Ldd's chunk */ + + SUsbcScBufferHeader* iEndpointHdr; /** @internalTechnology Pointer to the buffer Header for OUT/BI endpoints */ + TUint8* iBufferStartAddr; /** @internalTechnology IN/BI endpoint buffer start address within shared chunk */ + TUint iSize; /** @internalTechnology IN/BI endpoint buffer size within shared chunk */ + friend class RDevUsbcScClient; + }; + +/** +This class can be used to retrieve the geometry of the structures +within a shared chunk, as used by RDevUsbcScClient. + +@see RDevUsbcScClient +*/ + +class TUsbcScChunkHeader + { +public: +/** +The constructor for the TUsbcScChunkHeader class takes a RChunk object, +containing USBcSc data structures, and initialises itself, so that +GetNumberOfEndpoints & GetBuffer can be used to interpret the chunk structures. + +@param An RChunk object, which represents an shared chunk, containing the + USBcSc data structures to be retrieved. +*/ + IMPORT_C TUsbcScChunkHeader(RChunk aChunk); +/** +Retrieves the available information in the chunk, about the given endpoint, +on the given alternate setting. The returned TUsbcScBufferRecord, +represents the buffer geometry, used for for the endpoint, while +the filled in TUsbcScHdrEndpointRecord represents additional endpoint +information. + +@param aAltSetting The alternate setting, for which the provided endpoint number, is a member of. +@param aEndpoint The endpoint, who's buffer geometry is required. +@param aEndpointInf The provided record is filled in with details of the endpoint, who's number was given. +*/ + IMPORT_C TUsbcScBufferRecord* GetBuffer(TInt aAltSetting, TInt aEndpoint, TUsbcScHdrEndpointRecord*& aEndpointInf); +/** +Retrieves the number of endpoints found in a given alternate setting. +@param aAltSetting The alternate setting number, for which the number of endpoints contained within, is needed. +*/ + IMPORT_C TInt GetNumberOfEndpoints(TInt aAltSetting); + +public: + TUsbcScChunkBuffersHeader* iBuffers; /** A pointer to the TUsbcScChunkBuffersHeader object, within the chunk header */ + TUsbcScChunkAltSettingHeader* iAltSettings; /** A pointer to the TUsbcScChunkAltSettingHeader object, within the chunk header */ +private: + RChunk iChunk; + }; + +#endif + +#include + +#endif // __D32USBCSC_H__