// 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,

        };

    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,

        };

 // 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.