// Copyright (c) 2000-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\drivers\usbcshared.h

// Kernel side definitions for the USB Device driver stack (PIL + LDD).

// 

//

/**

 @file usbcshared.h

 @internalTechnology

*/

#ifndef __USBCSHARED_H__

#define __USBCSHARED_H__

//#include <drivers/usbcque.h>

#include <usb/usbcque.h>

// Define here what options are required:

// (USB_SUPPORTS_CONTROLENDPOINTS and USB_SUPPORTS_SET_DESCRIPTOR_REQUEST

//  have never been tested though...)

//#define USB_SUPPORTS_CONTROLENDPOINTS

//#define USB_SUPPORTS_SET_DESCRIPTOR_REQUEST

//#include <drivers/usbcdesc.h>

#include <usb/usbcdesc.h>

//#include <drivers/usbotgperipheralcontrolif.h>

#include <usb/usbotgperipheralcontrolif.h>

#include <usb/usb_peripheral_shai.h>

#include <usb/usb_charger_detection_shai.h>

#include <usb/usbcontrolxferif.h>

// FIXME: Remove this typedef once PIL and LDD are ready for SHAI

typedef UsbShai::TUsbPeripheralEvent TUsbcDeviceEvent;

typedef UsbShai::TUsbPeripheralPacketArray TUsbcPacketArray;

// Forward declaration

class DControlTransferManager;

class TUsbcSetup;

// Debug Support

// Use for debugging purposes only (commented out for normal operation):

//#define USBC_LDD_BUFFER_TRACE

static const char KUsbPILPanicCat[] = "USB PIL FAULT"; // kernel fault category

_LIT(KUsbPILKillCat, "USB PIL KILL");                    // thread kill category

_LIT(KUsbLDDKillCat, "USB LDD KILL");                    // thread kill category

/** Error code for stalled endpoint.

*/

const TInt KErrEndpointStall = KErrLocked;

/** Error code for Ep0 write prematurely ended by a host OUT token.

*/

const TInt KErrPrematureEnd = KErrDiskFull;

/** The following constants control the buffer arrangement for OUT transfers (IN transfers have only 1

    buffer). The total size of buffering for an OUT endpoint will be number of buffers * buffersize,

    so that, for example, a Bulk OUT endpoint will have KUsbcDmaBufNumBulk * KUsbcDmaBufSzBulk bytes of

    buffering.

    These buffers will be physically contiguous, so that DMA may be used.

    The number of buffers MUST be >=2 - otherwise the buffering scheme won't work.

    The buffer sizes should be an exact fraction of 4kB and the number of buffers such that the

    buffersize * number of buffers is an exact multiple of 4kB, otherwise memory will be wasted.

*/

/** Size of a Control ep buffer.

*/

const TInt KUsbcDmaBufSzControl = 1024;

/** Size of a Bulk ep buffer.

*/

const TInt KUsbcDmaBufSzBulk = 4096;

/** Size of an Interrupt ep buffer.

*/

const TInt KUsbcDmaBufSzInterrupt = 4096;

/** Size of an Isochronous ep buffer.

*/

const TInt KUsbcDmaBufSzIsochronous = 4096;

/** Number of buffers for Control OUT endpoints.

*/

const TInt KUsbcDmaBufNumControl = 2;

/** Number of buffers for Isochronous OUT endpoints.

*/

const TInt KUsbcDmaBufNumIsochronous = 2;

/** Number of buffers for Bulk OUT endpoints.

*/

const TInt KUsbcDmaBufNumBulk = 2;

/** Number of buffers for Interrupt OUT endpoints.

*/

const TInt KUsbcDmaBufNumInterrupt = 2;

/** Maximum buffer number.

*/

const TInt KUsbcDmaBufNumMax = MAX4(KUsbcDmaBufNumControl, KUsbcDmaBufNumIsochronous,

                                    KUsbcDmaBufNumBulk, KUsbcDmaBufNumInterrupt);

/** Maximum number of recorded packets possible.

*/

const TUint KUsbcDmaBufMaxPkts = 2;

/** Number of arrays.

*/

const TInt KUsbcDmaBufNumArrays = 2;

/** Max size that Ep0 packets might have.

*/

const TInt KUsbcBufSzControl = 64;

/** The Ep0 RX data collection buffer area.

    (Arbitrary size, judged to be sufficient for SET_DESCRIPTOR requests)

*/

const TInt KUsbcBufSz_Ep0Rx = 1024;

/** The Ep0 TX buffer area.

    (Size sufficient to hold as much data as can be requested via GET_DESCRIPTOR)

*/

const TInt KUsbcBufSz_Ep0Tx = 1024 * 64; 

/** The USB version the stack is compliant with: 2.0 (BCD).

*/

const TUint16 KUsbcUsbVersion = 0x0200;

/** Maximum number of endpoints an interface (i.e. LDD) may have.

*/

const TInt KUsbcMaxEpNumber = 5;

/** Status FIFO depth; enough for 2 complete configs.

*/

const TInt KUsbDeviceStatusQueueDepth = 15;

/** = 'no status info'.

*/

const TUint32 KUsbDeviceStatusNull = 0xffffffffu;

/** = 'no buffer available'.

*/

const TInt KUsbcInvalidBufferIndex = -1;

/** = 'no packet available'.

*/

const TUint KUsbcInvalidPacketIndex = (TUint)(-1);

/** = 'no drainable buffers'.

*/

const TInt KUsbcInvalidDrainQueueIndex = -1;

/** Number of possible bandwidth priorities.

*/

const TInt KUsbcDmaBufMaxPriorities = 4;

// The following buffer sizes are used within the LDD for the different

// user-selectable endpoint bandwidth priorities

// (EUsbcBandwidthOUTDefault/Plus1/Plus2/Maximum + the same for 'IN').

// These values, in particular those for the Maximum setting, were obtained

// empirically.

/** Bulk IN buffer sizes for different priorities (4K, 16K, 64K, 512K).

*/

const TInt KUsbcDmaBufSizesBulkIN[KUsbcDmaBufMaxPriorities] =

    {KUsbcDmaBufSzBulk, 0x4000, 0x10000, 0x80000};

/** Bulk OUT buffer sizes for different priorities (4K, 16K, 64K, 512K).

*/

const TInt KUsbcDmaBufSizesBulkOUT[KUsbcDmaBufMaxPriorities] =

    {KUsbcDmaBufSzBulk, 0x4000, 0x10000, 0x80000};

/** Number of UDCs supported in the system.

    (Support for more than one UDC is preliminary.)

*/

const TInt KUsbcMaxUdcs = 2;

/** Number of endpoints a USB device can have.

    (30 regular endpoints + 2 x Ep0)

*/

const TInt KUsbcEpArraySize = KUsbcMaxEndpoints + 2;

/** Number of notification requests of the same kind that can be registered at

    a time. As normally not more than one request per kind per LDD is

    permitted, this number is roughly equivalent to the maximum number of LDDs

    that can be operating at the same time.

    This constant is used by the PIL while maintaining its request lists

    (iClientCallbacks, iStatusCallbacks, iEpStatusCallbacks, iOtgCallbacks) to

    ensure that the lists are of a finite length and thus the list traverse

    time is bounded.

    This value is chosen with the maximum number of USB interfaces (not

    settings) allowed by the spec for a single device in mind.

*/

const TInt KUsbcMaxListLength = 256;

/**

 * device event FIFO depth, there are 5 different event define currently,

 * 10 should be enough

 */

const TInt KUsbDeviceEventQueueDepth = 10;

/** USB LDD client callback.

*/

class TUsbcClientCallback

    {

public:

    inline TUsbcClientCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);

    inline DBase* Owner() const;

    inline TInt DoCallback();

    inline void Cancel();

    inline void SetDfcQ(TDfcQue* aDfcQ);

public:

    /** Used by the PIL to queue callback objects into a TSglQue. */

    TSglQueLink iLink;

private:

    DBase* iOwner;

    TDfc iDfc;

    };

/** The endpoint halt/clear_halt status.

*/

class TUsbcEndpointStatusCallback

    {

public:

    inline TUsbcEndpointStatusCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);

    inline void SetState(TUint aState);

    inline TUint State() const;

    inline DBase* Owner() const;

    inline TInt DoCallback();

    inline void Cancel();

    inline void SetDfcQ(TDfcQue* aDfcQ);

public:

    /** Used by the PIL to queue callback objects into a TSglQue. */

    TSglQueLink iLink;

private:

    DBase* iOwner;

    TDfc iDfc;

    TUint iState;

    };

/** Maximum number of device status requests that can be queued at a time.

    The value chosen is thought to be sufficient in all situations.

*/

const TInt KUsbcDeviceStateRequests = 8;

/** The USB device status.

*/

class TUsbcStatusCallback

    {

public:

    inline TUsbcStatusCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);

    inline void SetState(UsbShai::TUsbPeripheralState aState);

    inline UsbShai::TUsbPeripheralState State(TInt aIndex) const;

    inline void ResetState();

    inline DBase* Owner() const;

    inline TInt DoCallback();

    inline void Cancel();

    inline void SetDfcQ(TDfcQue* aDfcQ);

public:

    /** Used by the PIL to queue callback objects into a TSglQue. */

    TSglQueLink iLink;

private:

    DBase* iOwner;

    TDfc iDfc;

    UsbShai::TUsbPeripheralState iState[KUsbcDeviceStateRequests];

    };

/** A USB transfer request.

    @publishedPartner

    @released

*/

class TUsbcRequestCallback : public UsbShai::TUsbPeripheralRequest

    {

public:

    /** @internalTechnology */

    inline TUsbcRequestCallback(const DBase* aOwner, TInt aEndpointNum, TDfcFn aDfcFunc,

                         TAny* aEndpoint, TDfcQue* aDfcQ, TInt aPriority);

    /** @internalTechnology    */

    inline ~TUsbcRequestCallback();

    IMPORT_C void SetRxBufferInfo(TUint8* aBufferStart,

                                      TUintPtr aBufferAddr,

                                      TUint32* aPacketIndex,

                                      TUint32* aPacketSize, 

                                      TInt aLength);

    IMPORT_C void SetTxBufferInfo(TUint8* aBufferStart, 

                                      TUintPtr aBufferAddr,

                                      TInt aLength);

    /** @internalTechnology    */

    inline void SetTransferDirection(UsbShai::TTransferDirection aTransferDir);

    /** @internalTechnology    */

    inline const DBase* Owner() const;

    /** @internalTechnology    */

    inline TInt DoCallback();

    /** @internalTechnology    */

    inline void Cancel();

public:

    /** Used by the PIL to queue callback objects into a TSglQue.

        @internalTechnology

    */

    TSglQueLink iLink;

public:

    /** The endpoint number. */

    const TInt iEndpointNum;

    /** Indicates the LDD client for this transfer. */

    const DBase* const iOwner;

    /** DFC, used by PIL to call back the LDD when transfer completes to the LDD. */

    TDfc iDfc;

    };

/** USB On-The-Go feature change callback.

*/

class TUsbcOtgFeatureCallback

    {

public:

    inline TUsbcOtgFeatureCallback(DBase* aOwner, TDfcFn aCallback, TInt aPriority);

    inline void SetFeatures(TUint8 aFeatures);

    inline TUint8 Features() const;

    inline DBase* Owner() const;

    inline TInt DoCallback();

    inline void Cancel();

    inline void SetDfcQ(TDfcQue* aDfcQ);

public:

    /** Used by the PIL to queue callback objects into a TSglQue. */

    TSglQueLink iLink;

private:

    DBase* iOwner;

    TDfc iDfc;

    TUint8 iValue;

    };

//

//########################### Physical Device Driver (PIL + PSL) ######################

//

class TUsbcLogicalEndpoint;

/** This models a physical (real) endpoint of the UDC.

*/

class TUsbcPhysicalEndpoint

    {

public:

    TUsbcPhysicalEndpoint();

    ~TUsbcPhysicalEndpoint();

    TBool EndpointSuitable(const TUsbcEndpointInfo* aEpInfo, TInt aIfcNumber) const; // Check Todo, SC will pass pointer to derived class

    TInt TypeAvailable(TUint aType) const;

    TInt DirAvailable(TUint aDir) const;

public:

    /** This endpoint's capabilities. */

    UsbShai::TUsbPeripheralEndpointCaps iCaps;

    /** USB address: 0x00, 0x80, 0x01, 0x81, etc. */

    TUint8 iEndpointAddr;

    /** Pointer to interface # this endpoint has been assigned to. */

    const TUint8* iIfcNumber;

    /** Pointer to corresponding logical endpoint or NULL. */

    const TUsbcLogicalEndpoint* iLEndpoint;

    /** Only used when searching for available endpoints. */

    TBool iSettingReserve;

    /** True if endpoint is halted (i.e. issues STALL handshakes), false otherwise. */

    TBool iHalt;

    };

class DUsbClientController;

class TUsbcInterface;

/** This is a 'logical' endpoint, as used by our device configuration model.

*/

class TUsbcLogicalEndpoint

    {

public:

    TUsbcLogicalEndpoint(DUsbClientController* aController, TUint aEndpointNum,

                         const TUsbcEndpointInfo& aEpInfo, TUsbcInterface* aInterface,

                         TUsbcPhysicalEndpoint* aPEndpoint);        // Check Todo, SC will pass pointer to derived class

    ~TUsbcLogicalEndpoint();

public:

    /** Pointer to controller object. */

    DUsbClientController* iController;

    /** The virtual (logical) endpoint number. */

    const TInt iLEndpointNum;

    /** This endpoint's info structure. */

    TUsbcEndpointInfo iInfo;                                        // Check Todo, SC will pass pointer to derived class

    /** Stores the endpoint size to be used for FS. */

    TInt iEpSize_Fs;

    /** Stores the endpoint size to be used for HS. */

    TInt iEpSize_Hs;

    /** 'Back' pointer. */

    const TUsbcInterface* iInterface;

    /** Pointer to corresponding physical endpoint, never NULL. */

    TUsbcPhysicalEndpoint* const iPEndpoint;

    };

class TUsbcInterfaceSet;

/** This is an 'alternate setting' of an interface.

*/

class TUsbcInterface

    {

public:

    TUsbcInterface(TUsbcInterfaceSet* aIfcSet, TUint8 aSetting, TBool aNoEp0Requests);

    ~TUsbcInterface();

public:

    /** Array of endpoints making up (belonging to) this setting. */

    RPointerArray<TUsbcLogicalEndpoint> iEndpoints;

    /** 'Back' pointer. */

    TUsbcInterfaceSet* const iInterfaceSet;

    /** bAlternateSetting (zero-based). */

    const TUint8 iSettingCode;

    /** KUsbcInterfaceInfo_NoEp0RequestsPlease: stall non-std Setup requests. */

    const TBool iNoEp0Requests;

    };

/** This is an 'interface' (owning 1 or more alternate settings).

    @see TUsbcInterface

*/

class TUsbcInterfaceSet

    {

public:

    TUsbcInterfaceSet(const DBase* aClientId, TUint8 aIfcNum);

    ~TUsbcInterfaceSet();

    inline const TUsbcInterface* CurrentInterface() const;

    inline TUsbcInterface* CurrentInterface();

public:

    /** Array of alternate settings provided by (belonging to) this interface. */

    RPointerArray<TUsbcInterface> iInterfaces;

    /** Pointer to the LDD which created and owns this interface. */

    const DBase* const iClientId;

    /** bInterfaceNumber (zero-based). */

    TUint8 iInterfaceNumber;

    /** bAlternateSetting (zero-based). */

    TUint8 iCurrentInterface;

    };

/** This is a 'configuration' of the USB device.

    Currently we support only one configuration.

*/

class TUsbcConfiguration

    {

public:

    TUsbcConfiguration(TUint8 aConfigVal);

    ~TUsbcConfiguration();

public:

    /** Array of interfaces making up (belonging to) this configuration. */

    RPointerArray<TUsbcInterfaceSet> iInterfaceSets;

    /** bConfigurationValue (one-based). */

    const TUint8 iConfigValue;

    };

/** The USB controller's power handler class.

*/

NONSHARABLE_CLASS(DUsbcPowerHandler) : public DPowerHandler

    {

public:

    void PowerUp();

    void PowerDown(TPowerState);

public:

    DUsbcPowerHandler(DUsbClientController* aController);

private:

    DUsbClientController* iController;

    };

/*

This is the EndpointInfo class used by the usb shared chunk client driver. 

*/

class TUsbcScEndpointInfo;

/**

Used to represent an array of (or inheriting from) TUsbcEndpointInfo objects.

@see DUsbClientController::SetInterface

*/

class TUsbcEndpointInfoArray

    {

public:

    typedef enum {EUsbcEndpointInfo, EUsbcScEndpointInfo} TArrayType;

    TUsbcEndpointInfoArray(const TUsbcEndpointInfo* aData, TInt aDataSize=0);

    TUsbcEndpointInfoArray(const TUsbcScEndpointInfo* aData, TInt aDataSize=0);

    inline TUsbcEndpointInfo& operator[](TInt aIndex) const; 

    TArrayType iType;

private:

    TUint8* iData;

    TInt iDataSize;

    };

class TUsbPeriDeviceEventQueue

    {

public:

    TUsbPeriDeviceEventQueue();

    void FifoAdd(TUsbcDeviceEvent aDeviceStatus);

    TUsbcDeviceEvent FifoGet();

private:

    TUsbcDeviceEvent iDeviceEventQueue[KUsbDeviceEventQueueDepth];