// 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,
ERequestChargingPortTypeNotify = 7,
ERequestMaxRequests, // 7
ERequestCancel = 0x40000000,
ERequestWriteDataCancel = ERequestWriteData | ERequestCancel,
ERequestReadDataNotifyCancel = ERequestReadDataNotify | ERequestCancel,
ERequestAlternateDeviceStatusNotifyCancel = ERequestAlternateDeviceStatusNotify | ERequestCancel,
ERequestReEnumerateCancel = ERequestReEnumerate | ERequestCancel,
ERequestEndpointStatusNotifyCancel = ERequestEndpointStatusNotify | ERequestCancel,
ERequestOtgFeaturesNotifyCancel = ERequestOtgFeaturesNotify | ERequestCancel,
ERequestChargingPortTypeNotifyCancel = ERequestChargingPortTypeNotify | 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,
EControlGetChargerDetectorCaps
};
// 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();
/** Register for notification on USB charger type' change. If any usb charger
is detected, request completes and current charger type value is filled in aValue.
@param aStatus Request status object
@param aValue On request completion, it contains current charger type value
*/
inline void ChargingPortTypeNotify(TRequestStatus& aStatus, TUint& aValue);
/** Cancel pending Charger Type request.
*/
inline void ChargingPortTypeNotifyCancel();
inline TInt ChargerDetectorCaps(TUsbcChargerDetectorProperties& aProperties);
/** 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__