--- 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 <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__