// Copyright (c) 2004-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:

// template\template_assp\pa_usbc.h

// Platform-dependent USB client controller layer (USB PSL).

// 

//

#ifndef __PA_USBC_H__

#define __PA_USBC_H__

// This is the header file for the implementation of the USB driver PSL layer for an imaginary USB client

// (device) controller.

// For simplicity's sake we assume the following endpoint layout of the controller.

// We have 5 endpoints in total - two Bulk endpoints (IN and OUT), two Isochronous endpoint (IN and OUT),

// one Interrupt endpoint (IN), and of course endpoint zero (Ep0).

//

// This is the mapping of "Hardware Endpoint Numbers" to "Real Endpoints" (and thus is also

// used as the array index for our local TTemplateAsspUsbcc::iEndpoints[]):

//

//	0 -	 0 (Ep0 OUT)

//	0 -	 1 (Ep0 IN)

//	1 -	 3 (Bulk  IN, Address 0x11, -> EpAddr2Idx(0x11) =  3)

//	2 -	 4 (Bulk OUT, Address 0x02, -> EpAddr2Idx(0x02) =  4)

//	3 -	 7 (Iso   IN, Address 0x13, -> EpAddr2Idx(0x13) =  7)

//	4 -	 8 (Iso  OUT, Address 0x04, -> EpAddr2Idx(0x04) =  8)

//	5 - 11 (Int   IN, Address 0x15, -> EpAddr2Idx(0x15) = 11)

//

// For the reason why this is so (or rather for the perhaps not so obvious system behind it),

// see the comment at the beginning of \e32\drivers\usbcc\ps_usbc.cpp and also the structure

// DeviceEndpoints[] at the top of pa_usbc.cpp.

// The total number of endpoints in our local endpoint array:

static const TInt KUsbTotalEndpoints = 12;

// The numbers used in the following macros are 'aRealEndpoint's (i.e. array indices):

#define IS_VALID_ENDPOINT(x)	((x) > 0 && (x) < KUsbTotalEndpoints)

#define IS_OUT_ENDPOINT(x)		((x) == 0 || (x) == 4 || (x) == 8)

#define IS_IN_ENDPOINT(x)		((x) == 1 || (x) == 3 || (x) == 7 || (x) == 11)

#define IS_BULK_IN_ENDPOINT(x)	((x) == 3)

#define IS_BULK_OUT_ENDPOINT(x) ((x) == 4)

#define IS_BULK_ENDPOINT(x)		(IS_BULK_IN_ENDPOINT(x) || IS_BULK_OUT_ENDPOINT(x))

#define IS_ISO_IN_ENDPOINT(x)	((x) == 7)

#define IS_ISO_OUT_ENDPOINT(x)	((x) == 8)

#define IS_ISO_ENDPOINT(x)		(IS_ISO_IN_ENDPOINT(x) || IS_ISO_OUT_ENDPOINT(x))

#define IS_INT_IN_ENDPOINT(x)	((x) == 11)

// This takes as an index the TTemplateAsspUsbcc::iEndpoints index (== aRealEndpoint) 0..11

// and returns the hardware endpoint number 0..5 (note that not all input indices are valid;

// these will return -1):

static const TInt TemplateAsspEndpoints[KUsbTotalEndpoints] =

	{0, 0, -1, 1, 2, -1, -1, 3, 4, -1, -1, 5};

// And here is a function to use the above array:

static inline TInt ArrayIdx2TemplateEp(TInt aRealEndpoint)

	{

	if (IS_VALID_ENDPOINT(aRealEndpoint)) return TemplateAsspEndpoints[aRealEndpoint];

	else return -1;

	}

// Endpoint max packet sizes

static const TInt KEp0MaxPktSz = 16;						// Control

static const TInt KIntMaxPktSz = 8;							// Interrupt

static const TInt KBlkMaxPktSz = 64;						// Bulk

static const TInt KIsoMaxPktSz = 256;						// Isochronous

static const TInt KEp0MaxPktSzMask = KUsbEpSize16;			// Control

static const TInt KIntMaxPktSzMask = KUsbEpSize8;			// Interrupt

static const TInt KBlkMaxPktSzMask = KUsbEpSize64;			// Bulk

static const TInt KIsoMaxPktSzMask = KUsbEpSize256;			// Isochronous

// 1 ms (i.e. the shortest delay possible with the sort of timer used) seems to give

// the best results, both for Bulk and Iso, and also (in the USBRFLCT test program)

// both for loop tests as well as unidirectional transfers.

static const TInt KRxTimerTimeout = 1;						// milliseconds

// Used in descriptors

static const TUint16 KUsbVendorId	= KUsbVendorId_Symbian;	// Symbian

static const TUint16 KUsbProductId	= 0x0666;				// bogus...

static const TUint16 KUsbDevRelease = 0x0100;				// bogus... (BCD!)

static const TUint16 KUsbLangId		= 0x0409;				// English (US) Language ID

// String descriptor default values

static const wchar_t KStringManufacturer[] = L"Nokia Corporation and/or its subsidiary(-ies).";

static const wchar_t KStringProduct[]	   = L"Template USB Test Driver";

static const wchar_t KStringSerialNo[]	   = L"0123456789";

static const wchar_t KStringConfig[]	   = L"First and Last and Always";

// We use our own Ep0 state enum:

enum TEp0State

	{

	EP0_IDLE = 0,											// These identifiers don't conform to

	EP0_OUT_DATA_PHASE = 1,									// Symbian's coding standard... ;)

	EP0_IN_DATA_PHASE = 2,

	EP0_END_XFER = 3,

	};

class TTemplateAsspUsbcc;

// The lowest level endpoint abstraction

struct TEndpoint

	{

	TEndpoint();

	static void RxTimerCallback(TAny* aPtr);

	// data

	TTemplateAsspUsbcc* iController;						// pointer to controller object

	union

		{

		TUint8* iRxBuf;										// where to store /

		const TUint8* iTxBuf;								// from where to send

		};

	union

		{

		TInt iReceived;										// bytes already rx'ed /

		TInt iTransmitted;									// bytes already tx'ed

		};

	TInt iLength;											// number of bytes to be transferred

	TBool iZlpReqd;											// ZeroLengthPacketRequired

	TBool iNoBuffer;										// no data buffer was available when it was needed

	TBool iDisabled;										// dto but stronger

	TInt iPackets;											// number of packets rx'ed or tx'ed

	TInt iLastError;										//

	TUsbcRequestCallback* iRequest;							//

	NTimer iRxTimer;										//

	TBool iRxTimerSet;										// true if iRxTimer is running

	TBool iRxMoreDataRcvd;									// true if after setting timer data have arrived

	TUsbcPacketArray* iPacketIndex;							// actually TUsbcPacketArray (*)[]

	TUsbcPacketArray* iPacketSize;							// actually TUsbcPacketArray (*)[]

	};

// The hardware driver object proper

class TTemplate;

class TTemplateAsspUsbcc : public DUsbClientController

	{

friend void TEndpoint::RxTimerCallback(TAny*);

public:

	TTemplateAsspUsbcc();

	TInt Construct();

	virtual ~TTemplateAsspUsbcc();

	virtual void DumpRegisters();

private:

	virtual TInt SetDeviceAddress(TInt aAddress);

	virtual TInt ConfigureEndpoint(TInt aRealEndpoint, const TUsbcEndpointInfo& aEndpointInfo);

	virtual TInt DeConfigureEndpoint(TInt aRealEndpoint);

	virtual TInt AllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource);

	virtual TInt DeAllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource);

	virtual TBool QueryEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource) const;

	virtual TInt OpenDmaChannel(TInt aRealEndpoint);

	virtual void CloseDmaChannel(TInt aRealEndpoint);

	virtual TInt SetupEndpointRead(TInt aRealEndpoint, TUsbcRequestCallback& aCallback);

	virtual TInt SetupEndpointWrite(TInt aRealEndpoint, TUsbcRequestCallback& aCallback);

	virtual TInt CancelEndpointRead(TInt aRealEndpoint);

	virtual TInt CancelEndpointWrite(TInt aRealEndpoint);

	virtual TInt SetupEndpointZeroRead();

	virtual TInt SetupEndpointZeroWrite(const TUint8* aBuffer, TInt aLength, TBool aZlpReqd = EFalse);

	virtual TInt SendEp0ZeroByteStatusPacket();

	virtual TInt StallEndpoint(TInt aRealEndpoint);

	virtual TInt ClearStallEndpoint(TInt aRealEndpoint);

	virtual TInt EndpointStallStatus(TInt aRealEndpoint) const;

	virtual TInt EndpointErrorStatus(TInt aRealEndpoint) const;

	virtual TInt ResetDataToggle(TInt aRealEndpoint);

	virtual TInt SynchFrameNumber() const;

	virtual void SetSynchFrameNumber(TInt aFrameNumber);

	virtual TInt StartUdc();

	virtual TInt StopUdc();

	virtual TInt UdcConnect();

	virtual TInt UdcDisconnect();

	virtual TBool UsbConnectionStatus() const;

	virtual TBool UsbPowerStatus() const;

	virtual TBool DeviceSelfPowered() const;

	virtual const TUsbcEndpointCaps* DeviceEndpointCaps() const;

	virtual TInt DeviceTotalEndpoints() const;

	virtual TBool SoftConnectCaps() const;

	virtual TBool DeviceStateChangeCaps() const;

	virtual void Suspend();

	virtual void Resume();

	virtual void Reset();

	virtual TInt SignalRemoteWakeup();

	virtual void Ep0ReadSetupPktProceed();

	virtual void Ep0ReceiveProceed();

	virtual TDfcQue* DfcQ(TInt aUnit);

private:

	// general

	void EnableEndpointInterrupt(TInt aEndpoint);

	void DisableEndpointInterrupt(TInt aEndpoint);

	void ClearEndpointInterrupt(TInt aEndpoint);

	void InitialiseUdcRegisters();

	void UdcEnable();

	void UdcDisable();

	TInt SetupUdcInterrupt();

	void ReleaseUdcInterrupt();

	void UdcInterruptService();

	void EndpointIntService(TInt aEndpoint);

	TInt ResetIntService();

	void SuspendIntService();

	void ResumeIntService();

	void SofIntService();

	static void UdcIsr(TAny* aPtr);

	static TInt UsbClientConnectorCallback(TAny* aPtr);

	// endpoint zero

	void Ep0IntService();

	void Ep0ReadSetupPkt();

	void Ep0Receive();

	void Ep0Transmit();

	void Ep0EndXfer();

	void Ep0Cancel();

	void Ep0PrematureStatusOut();

	void Ep0StatusIn();

	void Ep0NextState(TEp0State aNextState);

	// endpoint n with n != 0

	void BulkTransmit(TInt aEndpoint);

	void BulkReceive(TInt aEndpoint);

	void BulkReadRxFifo(TInt aEndpoint);

	void IsoTransmit(TInt aEndpoint);

	void IsoReceive(TInt aEndpoint);

	void IsoReadRxFifo(TInt aEndpoint);

	void IntTransmit(TInt aEndpoint);

	void RxComplete(TEndpoint* aEndpoint);

	void StopRxTimer(TEndpoint* aEndpoint);

private:

	// general

	TBool iSoftwareConnectable;

	TBool iCableDetectable;

	TBool iCableConnected;

	TBool iBusIsPowered;

	TBool iInitialized;

	TInt (*iUsbClientConnectorCallback)(TAny *);

	TemplateAssp* iAssp;

	// endpoint zero

	TBool iEp0Configured;

	TEp0State iEp0State;

	// endpoints n

	TEndpoint iEndpoints[KUsbTotalEndpoints];				// for how this is indexed, see top of pa_usbc.cpp

	};

#endif // __PA_USBC_H__