--- /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 <e32ver.h>
+#include <usb/usb.h>
+#include <usb/d32usbcshared.h>
+
+
+/** 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<TUsbcScInterfaceInfo> 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<TUint8*>(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 <usb/d32usbcsc.inl>
+
+#endif // __D32USBCSC_H__