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

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

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

/** Used by the LDD.

*/

typedef TUint32 TUsbcPacketArray;

/** Used as a return value from DUsbClientController::EnquireEp0NextState(),

	the purpose of which is to enable the PSL to find out what the next stage

	will be for a newly received Setup packet.

	The enum values are self-explanatory.

	@publishedPartner

	@released

*/

enum TUsbcEp0State

	{

	EEp0StateDataIn,

	EEp0StateDataOut,

	EEp0StateStatusIn

	};

/** Used to show the direction of a transfer request to the Controller.

	@see TUsbcRequestCallback

*/

enum TTransferDirection {EControllerNone, EControllerRead, EControllerWrite};

/** These event codes are used by the PSL to tell the PIL what has happened.

	@publishedPartner

	@released

*/

enum TUsbcDeviceEvent

	{

	/** The USB Suspend bus state has been detected. */

	EUsbEventSuspend,

	/** USB Resume signalling has been detected. */

	EUsbEventResume,

	/** A USB Reset condition has been detected. */

	EUsbEventReset,

	/** Physical removal of the USB cable has been detected. */

	EUsbEventCableRemoved,

	/** Physical insertion of the USB cable has been detected. */

	EUsbEventCableInserted

	};

/** 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(TUsbcDeviceState aState);

	inline TUsbcDeviceState 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;

	TUsbcDeviceState iState[KUsbcDeviceStateRequests];

	};

/** A USB transfer request.

	@publishedPartner

	@released

*/

class TUsbcRequestCallback

	{

public:

	/** @internalTechnology */

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

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

	/** @internalTechnology	*/

	inline ~TUsbcRequestCallback();

	/** @internalTechnology	*/

	inline void SetRxBufferInfo(TUint8* aBufferStart, TPhysAddr aBufferAddr,

								TUsbcPacketArray* aPacketIndex, TUsbcPacketArray* aPacketSize,

								TInt aLength);

	/** @internalTechnology	*/

	inline void SetTxBufferInfo(TUint8* aBufferStart, TPhysAddr aBufferAddr, TInt aLength);

	/** @internalTechnology	*/

	inline void SetTransferDirection(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;

	/** The 'real' endpoint number, as used by the PDD. */

	TInt iRealEpNum;

	/** 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;

	/** Direction of transfer request. */

	TTransferDirection iTransferDir;

	/** Start address of this buffer. */

	TUint8* iBufferStart;

	/** Physical address of buffer start (used for DMA). */

	TPhysAddr iBufferAddr;

	/** Array of pointers into iBufferStart (actually TUsbcPacketArray (*)[]). */

	TUsbcPacketArray* iPacketIndex;

	/** Array of packet sizes (actually TUsbcPacketArray (*)[]). */

	TUsbcPacketArray* iPacketSize;

	/** Length in bytes of buffer (iBufferStart). */

	TInt iLength;

	/** For IN transfers, if a zlp might be required at the end of this transfer. */

	TBool iZlpReqd;

	/** Number of bytes transmitted; changed by the PSL. */

	TUint iTxBytes;

	/** Number of packets received (if it is a read); changed by the PSL. */

	TUint iRxPackets;

	/** The error code upon completion of the request; changed by the PSL. */

	TInt iError;

	};

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

	TUsbcEndpointCaps 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;

	};

/** A USB Setup packet.

	Used mainly internally by the PIL but also by

	DUsbClientController::ProcessSetConfiguration(const TUsbcSetup&),

	which is classified as publishedPartner.

	@publishedPartner @released

*/

struct TUsbcSetup

	{