diff -r f92a4f87e424 -r 012cc2ee6408 usbdrv/peripheral/public/d32usbcsc.h --- a/usbdrv/peripheral/public/d32usbcsc.h Tue Aug 31 17:01:47 2010 +0300 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1558 +0,0 @@ -// 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__