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

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

// 

//

#include <template_assp.h>									// /assp/template_assp/

#include <template_assp_priv.h>								// /assp/template_assp/

#include <drivers/usbc.h>

#include "pa_usbc.h"										// .

// Debug support

#ifdef _DEBUG

static const char KUsbPanicCat[] = "USB PSL";

#endif

// Define USB_SUPPORTS_PREMATURE_STATUS_IN to enable proper handling of a premature STATUS_IN stage, i.e. a

// situation where the host sends less data than first announced and instead of more data (OUT) will send an

// IN token to start the status stage. What we do in order to implement this here is to prime the TX fifo with

// a ZLP immediately when we find out that we're dealing with a DATA_OUT request. This way, as soon as the

// premature IN token is received, we complete the transaction by sending off the ZLP. If we don't prime the

// TX fifo then there is no way for us to recognise a premature status because the IN token itself doesn't

// raise an interrupt. We would simply wait forever for more data, or rather we would time out and the host

// would move on and send the next Setup packet.

// The reason why we would not want to implement the proper behaviour is this: After having primed the TX fifo

// with a ZLP, it is impossible for a user to reject such a (class/vendor specific) Setup request, basically

// because the successful status stage happens automatically. At the time the user has received and decoded

// the Setup request there's for her no way to stall Ep0 in order to show to the host that this Setup packet

// is invalid or inappropriate or whatever, because she cannot prevent the status stage from happening.

// (All this is strictly true only if the amount of data in the data stage is less than or equal to Ep0's max

//	packet size. However this is almost always the case.)

//#define USB_SUPPORTS_PREMATURE_STATUS_IN

static const TUsbcEndpointCaps DeviceEndpoints[KUsbTotalEndpoints] =

	{

	//                                                      Hardware #    iEndpoints index

	{KEp0MaxPktSzMask,	(KUsbEpTypeControl	   | KUsbEpDirOut)}, //	 0 -  0

	{KEp0MaxPktSzMask,	(KUsbEpTypeControl	   | KUsbEpDirIn )}, //	 0 -  1

	{KUsbEpNotAvailable, KUsbEpNotAvailable},				// --- Not present

	{KBlkMaxPktSzMask,	(KUsbEpTypeBulk		   | KUsbEpDirIn )}, //	 1 -  3

	{KBlkMaxPktSzMask,	(KUsbEpTypeBulk		   | KUsbEpDirOut)}, //	 2 -  4

	{KUsbEpNotAvailable, KUsbEpNotAvailable},				// --- Not present

	{KUsbEpNotAvailable, KUsbEpNotAvailable},				// --- Not present

	{KIsoMaxPktSzMask,	(KUsbEpTypeIsochronous | KUsbEpDirIn )}, //	 3 -  7

	{KIsoMaxPktSzMask,	(KUsbEpTypeIsochronous | KUsbEpDirOut)}, //	 4 -  8

	{KUsbEpNotAvailable, KUsbEpNotAvailable},				// --- Not present

	{KUsbEpNotAvailable, KUsbEpNotAvailable},				// --- Not present

	{KIntMaxPktSzMask,	(KUsbEpTypeInterrupt   | KUsbEpDirIn )}, //	 5 - 11

	};

// --- TEndpoint --------------------------------------------------------------

TEndpoint::TEndpoint()

//

// Constructor

//

	: iRxBuf(NULL), iReceived(0), iLength(0), iZlpReqd(EFalse), iNoBuffer(EFalse), iDisabled(EFalse),

	  iPackets(0), iLastError(KErrNone), iRequest(NULL), iRxTimer(RxTimerCallback, this),

	  iRxTimerSet(EFalse), iRxMoreDataRcvd(EFalse), iPacketIndex(NULL), iPacketSize(NULL)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TEndpoint::TEndpoint"));

	}

void TEndpoint::RxTimerCallback(TAny* aPtr)

//

// (This function is static.)

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TEndpoint::RxTimerCallback"));

	TEndpoint* const ep = static_cast<TEndpoint*>(aPtr);

	if (!ep)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !ep"));

		}

	else if (!ep->iRxTimerSet)

		{

		// Timer 'stop' substitute (instead of stopping it,

		// we just let it expire after clearing iRxTimerSet)

		__KTRACE_OPT(KUSB, Kern::Printf("!ep->iRxTimerSet - returning"));

		}

	else if (!ep->iRxBuf)

		{

		// Request already completed

		__KTRACE_OPT(KUSB, Kern::Printf("!ep->iRxBuf - returning"));

		}

	else if (ep->iRxMoreDataRcvd)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > rx timer cb: not yet completing..."));

		ep->iRxMoreDataRcvd = EFalse;

		ep->iRxTimer.Again(KRxTimerTimeout);

		}

	else

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > rx timer cb: completing now..."));

		*ep->iPacketSize = ep->iReceived;

		ep->iController->RxComplete(ep);

		}

	}

// --- TTemplateAsspUsbcc public ---------------------------------------------------

TTemplateAsspUsbcc::TTemplateAsspUsbcc()

//

// Constructor.

//

	: iCableConnected(ETrue), iBusIsPowered(EFalse),

	  iInitialized(EFalse), iUsbClientConnectorCallback(UsbClientConnectorCallback),

	  iEp0Configured(EFalse)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::TTemplateAsspUsbcc"));

	iAssp = static_cast<TemplateAssp*>(Arch::TheAsic());

	iSoftwareConnectable = iAssp->UsbSoftwareConnectable();

	iCableDetectable = iAssp->UsbClientConnectorDetectable();

	if (iCableDetectable)

		{

		// Register our callback for detecting USB cable insertion/removal.

		// We ignore the error code: if the registration fails, we just won't get any events.

		// (Which of course is bad enough...)

		(void) iAssp->RegisterUsbClientConnectorCallback(iUsbClientConnectorCallback, this);

		// Call the callback straight away so we get the proper PIL state from the beginning.

		(void) UsbClientConnectorCallback(this);

		}

	for (TInt i = 0; i < KUsbTotalEndpoints; i++)

		{

		iEndpoints[i].iController = this;

		}

	}

TInt TTemplateAsspUsbcc::Construct()

//

// Construct.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::Construct"));

	TUsbcDeviceDescriptor* DeviceDesc = TUsbcDeviceDescriptor::New(

		0x00,												// aDeviceClass

		0x00,												// aDeviceSubClass

		0x00,												// aDeviceProtocol

		KEp0MaxPktSz,										// aMaxPacketSize0

		KUsbVendorId,										// aVendorId

		KUsbProductId,										// aProductId

		KUsbDevRelease,										// aDeviceRelease

		1);													// aNumConfigurations

	if (!DeviceDesc)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for dev desc failed."));

		return KErrGeneral;

		}

	TUsbcConfigDescriptor* ConfigDesc = TUsbcConfigDescriptor::New(

		1,													// aConfigurationValue

		ETrue,												// aSelfPowered (see 12.4.2 "Bus-Powered Devices")

		ETrue,												// aRemoteWakeup

		0);													// aMaxPower (mA)

	if (!ConfigDesc)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for config desc failed."));

		return KErrGeneral;

		}

	TUsbcLangIdDescriptor* StringDescLang = TUsbcLangIdDescriptor::New(KUsbLangId);

	if (!StringDescLang)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for lang id $ desc failed."));

		return KErrGeneral;

		}

	// ('sizeof(x) - 2' because 'wchar_t KStringXyz' created a wide string that ends in '\0\0'.)

	TUsbcStringDescriptor* StringDescManu =

		TUsbcStringDescriptor::New(TPtr8(

									   const_cast<TUint8*>(reinterpret_cast<const TUint8*>(KStringManufacturer)),

									   sizeof(KStringManufacturer) - 2, sizeof(KStringManufacturer) - 2));

	if (!StringDescManu)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for manufacturer $ desc failed."));

		return KErrGeneral;

		}

	TUsbcStringDescriptor* StringDescProd =

		TUsbcStringDescriptor::New(TPtr8(

									   const_cast<TUint8*>(reinterpret_cast<const TUint8*>(KStringProduct)),

									   sizeof(KStringProduct) - 2, sizeof(KStringProduct) - 2));

	if (!StringDescProd)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for product $ desc failed."));

		return KErrGeneral;

		}

	TUsbcStringDescriptor* StringDescSer =

		TUsbcStringDescriptor::New(TPtr8(

									   const_cast<TUint8*>(reinterpret_cast<const TUint8*>(KStringSerialNo)),

									   sizeof(KStringSerialNo) - 2, sizeof(KStringSerialNo) - 2));

	if (!StringDescSer)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for serial no $ desc failed."));

		return KErrGeneral;

		}

	TUsbcStringDescriptor* StringDescConf =

		TUsbcStringDescriptor::New(TPtr8(

									   const_cast<TUint8*>(reinterpret_cast<const TUint8*>(KStringConfig)),

									   sizeof(KStringConfig) - 2, sizeof(KStringConfig) - 2));

	if (!StringDescConf)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Memory allocation for config $ desc failed."));

		return KErrGeneral;

		}

	const TBool r =	InitialiseBaseClass(DeviceDesc,

										ConfigDesc,

										StringDescLang,

										StringDescManu,

										StringDescProd,

										StringDescSer,

										StringDescConf);

	if (!r)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: UsbClientController::InitialiseBaseClass failed."));

		return KErrGeneral;

		}

	return KErrNone;

	}

TTemplateAsspUsbcc::~TTemplateAsspUsbcc()

//

// Destructor.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::~TTemplateAsspUsbcc"));

	// Unregister our callback for detecting USB cable insertion/removal

	if (iCableDetectable)

		{

		iAssp->UnregisterUsbClientConnectorCallback();

		}

	if (iInitialized)

		{

		// (The explicit scope operator is used against Lint warning #1506.)

		TTemplateAsspUsbcc::StopUdc();

		}

	}

TBool TTemplateAsspUsbcc::DeviceStateChangeCaps() const

//

// Returns capability of hardware to accurately track the device state (Chapter 9 state).

//

	{

	// TO DO: Return EFalse or ETrue here, depending on whether the UDC supports exact device state tracking

	// (most don't).

	return EFalse;

	}

TInt TTemplateAsspUsbcc::SignalRemoteWakeup()

//

// Forces the UDC into a non-idle state to perform a remote wakeup operation.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SignalRemoteWakeup"));

	// TO DO: Do here whatever is necessary for the UDC to signal remote wakeup.

	return KErrNone;

	}

void TTemplateAsspUsbcc::DumpRegisters()

//

// Dumps the contents of a number of UDC registers to the screen (using Kern::Printf()).

// Rarely used, but might prove helpful when needed.

//

	{

	Kern::Printf("TCotullaUsbcc::DumpRegisters:");

	// TO DO: Print the contents of some (or all) UDC registers here.

	}

TDfcQue* TTemplateAsspUsbcc::DfcQ(TInt /* aUnit */)

//

// Returns a pointer to the kernel DFC queue to be used buy the USB LDD.

//

	{

	return Kern::DfcQue0();

	}

// --- TTemplateAsspUsbcc private virtual ------------------------------------------

TInt TTemplateAsspUsbcc::SetDeviceAddress(TInt aAddress)

//

// Sets the PIL-provided device address manually (if possible - otherwise do nothing).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetDeviceAddress: %d", aAddress));

	// TO DO (optional): Set device address here.

	if (aAddress)

		{

		// Address can be zero.

		MoveToAddressState();

		}

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::ConfigureEndpoint(TInt aRealEndpoint, const TUsbcEndpointInfo& aEndpointInfo)

//

// Prepares (enables) an endpoint (incl. Ep0) for data transmission or reception.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::ConfigureEndpoint(%d)", aRealEndpoint));

	const TInt n = ArrayIdx2TemplateEp(aRealEndpoint);

	if (n < 0)

		return KErrArgument;

	TEndpoint* const ep = &iEndpoints[aRealEndpoint];

	if (ep->iDisabled == EFalse)

		{

		EnableEndpointInterrupt(n);

		}

	ep->iNoBuffer = EFalse;

	if (n == 0)

		iEp0Configured = ETrue;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::DeConfigureEndpoint(TInt aRealEndpoint)

//

// Disables an endpoint (incl. Ep0).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::DeConfigureEndpoint(%d)", aRealEndpoint));

	const TInt n = ArrayIdx2TemplateEp(aRealEndpoint);

	if (n < 0)

		return KErrArgument;

	DisableEndpointInterrupt(n);

	if (n == 0)

		iEp0Configured = EFalse;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::AllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource)

//

// Puts the requested endpoint resource to use, if possible.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::AllocateEndpointResource(%d): %d",

									aRealEndpoint, aResource));

	// TO DO: Allocate endpoint resource here.

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::DeAllocateEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource)

//

// Stops the use of the indicated endpoint resource, if beneficial.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::DeAllocateEndpointResource(%d): %d",

									aRealEndpoint, aResource));

	// TO DO: Deallocate endpoint resource here.

	return KErrNone;

	}

TBool TTemplateAsspUsbcc::QueryEndpointResource(TInt aRealEndpoint, TUsbcEndpointResource aResource) const

//

// Returns the status of the indicated resource and endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::QueryEndpointResource(%d): %d",

									aRealEndpoint, aResource));

	// TO DO: Query endpoint resource here. The return value should reflect the actual state.

	return ETrue;

	}

TInt TTemplateAsspUsbcc::OpenDmaChannel(TInt aRealEndpoint)

//

// Opens a DMA channel for this endpoint. This function is always called during the creation of an endpoint

// in the PIL. If DMA channels are a scarce resource, it's possible to do nothing here and wait for an

// AllocateEndpointResource call instead.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::OpenDmaChannel(%d)", aRealEndpoint));

	// TO DO (optional): Open DMA channel here.

	// An error should only  be returned in case of an actual DMA problem.

	return KErrNone;

	}

void TTemplateAsspUsbcc::CloseDmaChannel(TInt aRealEndpoint)

//

// Closes a DMA channel for this endpoint. This function is always called during the destruction of an

// endpoint in the PIL.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::CloseDmaChannel(%d)", aRealEndpoint));

	// TO DO (optional): Close DMA channel here (only if it was opened via OpenDmaChannel).

	}

TInt TTemplateAsspUsbcc::SetupEndpointRead(TInt aRealEndpoint, TUsbcRequestCallback& aCallback)

//

// Sets up a read request for an endpoint on behalf of the LDD.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetupEndpointRead(%d)", aRealEndpoint));

	if (!IS_OUT_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !IS_OUT_ENDPOINT(%d)", aRealEndpoint));

		return KErrArgument;

		}

	TEndpoint* const ep = &iEndpoints[aRealEndpoint];

	if (ep->iRxBuf != NULL)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > WARNING: iEndpoints[%d].iRxBuf != NULL", aRealEndpoint));

		return KErrGeneral;

		}

	ep->iRxBuf = aCallback.iBufferStart;

	ep->iReceived = 0;

	ep->iLength = aCallback.iLength;

	// For Bulk reads we start out with the assumption of 1 packet (see BulkReceive for why):

	ep->iPackets = IS_BULK_OUT_ENDPOINT(aRealEndpoint) ? 1 : 0;

	ep->iRequest = &aCallback;

	ep->iPacketIndex = aCallback.iPacketIndex;

	if (IS_BULK_OUT_ENDPOINT(aRealEndpoint))

		*ep->iPacketIndex = 0;								// a one-off optimization

	ep->iPacketSize = aCallback.iPacketSize;

	const TInt n = ArrayIdx2TemplateEp(aRealEndpoint);

	if (ep->iDisabled)

		{

		ep->iDisabled = EFalse;

		EnableEndpointInterrupt(n);

		}

	else if (ep->iNoBuffer)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > There had been no Rx buffer available: reading Rx FIFO now"));

		ep->iNoBuffer = EFalse;

		if (IS_BULK_OUT_ENDPOINT(aRealEndpoint))

			{

			BulkReadRxFifo(n);

			}

		else if (IS_ISO_OUT_ENDPOINT(aRealEndpoint))

			{

			IsoReadRxFifo(n);

			}

		else

			{

			__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Endpoint not found"));

			}

		}

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::SetupEndpointWrite(TInt aRealEndpoint, TUsbcRequestCallback& aCallback)

//

// Sets up a write request for an endpoint on behalf of the LDD.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetupEndpointWrite(%d)", aRealEndpoint));

	if (!IS_IN_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !IS_IN_ENDPOINT(%d)", aRealEndpoint));

		return KErrArgument;

		}

	TEndpoint* const ep = &iEndpoints[aRealEndpoint];

	if (ep->iTxBuf != NULL)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: iEndpoints[%d].iTxBuf != NULL", aRealEndpoint));

		return KErrGeneral;

		}

	ep->iTxBuf = aCallback.iBufferStart;

	ep->iTransmitted = 0;

	ep->iLength = aCallback.iLength;

	ep->iPackets = 0;

	ep->iZlpReqd = aCallback.iZlpReqd;

	ep->iRequest = &aCallback;

	const TInt n = ArrayIdx2TemplateEp(aRealEndpoint);

	if (IS_BULK_IN_ENDPOINT(aRealEndpoint))

		{

		if (ep->iDisabled)

			{

			ep->iDisabled = EFalse;

			EnableEndpointInterrupt(n);

			}

		BulkTransmit(n);

		}

	else if (IS_ISO_IN_ENDPOINT(aRealEndpoint))

		{

		IsoTransmit(n);

		}

	else if (IS_INT_IN_ENDPOINT(aRealEndpoint))

		{

		IntTransmit(n);

		}

	else

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Endpoint not found"));

		}

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::CancelEndpointRead(TInt aRealEndpoint)

//

// Cancels a read request for an endpoint on behalf of the LDD.

// No completion to the PIL occurs.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::CancelEndpointRead(%d)", aRealEndpoint));

	if (!IS_OUT_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !IS_OUT_ENDPOINT(%d)", aRealEndpoint));

		return KErrArgument;

		}

	TEndpoint* const ep = &iEndpoints[aRealEndpoint];

	if (ep->iRxBuf == NULL)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > WARNING: iEndpoints[%d].iRxBuf == NULL", aRealEndpoint));

		return KErrNone;

		}

	ep->iRxBuf = NULL;

	ep->iReceived = 0;

	ep->iNoBuffer = EFalse;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::CancelEndpointWrite(TInt aRealEndpoint)

//

// Cancels a write request for an endpoint on behalf of the LDD.

// No completion to the PIL occurs.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::CancelEndpointWrite(%d)", aRealEndpoint));

	if (!IS_IN_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !IS_IN_ENDPOINT(%d)", aRealEndpoint));

		return KErrArgument;

		}

	TEndpoint* const ep = &iEndpoints[aRealEndpoint];

	if (ep->iTxBuf == NULL)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > WARNING: iEndpoints[%d].iTxBuf == NULL", aRealEndpoint));

		return KErrNone;

		}

	// TO DO (optional): Flush the Ep's Tx FIFO here, if possible.

	ep->iTxBuf = NULL;

	ep->iTransmitted = 0;

	ep->iNoBuffer = EFalse;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::SetupEndpointZeroRead()

//

// Sets up an Ep0 read request (own function due to Ep0's special status).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetupEndpointZeroRead"));

	TEndpoint* const ep = &iEndpoints[KEp0_Out];

	if (ep->iRxBuf != NULL)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > WARNING: iEndpoints[%d].iRxBuf != NULL", KEp0_Out));

		return KErrGeneral;

		}

	ep->iRxBuf = iEp0_RxBuf;

	ep->iReceived = 0;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::SetupEndpointZeroWrite(const TUint8* aBuffer, TInt aLength, TBool aZlpReqd)

//

// Sets up an Ep0 write request (own function due to Ep0's special status).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetupEndpointZeroWrite"));

	TEndpoint* const ep = &iEndpoints[KEp0_In];

	if (ep->iTxBuf != NULL)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: iEndpoints[%d].iTxBuf != NULL", KEp0_In));

		return KErrGeneral;

		}

	ep->iTxBuf = aBuffer;

	ep->iTransmitted = 0;

	ep->iLength = aLength;

	ep->iZlpReqd = aZlpReqd;

	ep->iRequest = NULL;

	Ep0Transmit();

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::SendEp0ZeroByteStatusPacket()

//

// Sets up an Ep0 write request for zero bytes.

// This is a separate function because no data transfer is involved here.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SendEp0ZeroByteStatusPacket"));

	// This is possibly a bit tricky. When this function is called it just means that the higher layer wants a

	// ZLP to be sent. Whether we actually send one manually here depends on a number of factors, as the

	// current Ep0 state (i.e. the stage of the Ep0 Control transfer), and, in case the hardware handles some

	// ZLPs itself, whether it might already handle this one.

	// Here is an example of what the checking of the conditions might look like:

#ifndef USB_SUPPORTS_SET_DESCRIPTOR_REQUEST

	if ((!iEp0ReceivedNonStdRequest && iEp0State == EP0_IN_DATA_PHASE) ||

#else

	if ((!iEp0ReceivedNonStdRequest && iEp0State != EP0_IDLE) ||

#endif

#ifdef USB_SUPPORTS_PREMATURE_STATUS_IN

		(iEp0ReceivedNonStdRequest && iEp0State != EP0_OUT_DATA_PHASE))

#else

		(iEp0ReceivedNonStdRequest))

#endif

		{

		// TO DO: Arrange for the sending of a ZLP here.

		}

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::StallEndpoint(TInt aRealEndpoint)

//

// Stalls an endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::StallEndpoint(%d)", aRealEndpoint));

	if (IS_ISO_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Iso endpoint cannot be stalled"));

		return KErrArgument;

		}

	// TO DO: Stall the endpoint here.

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::ClearStallEndpoint(TInt aRealEndpoint)

//

// Clears the stall condition of an endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::ClearStallEndpoint(%d)", aRealEndpoint));

	if (IS_ISO_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Iso endpoint cannot be unstalled"));

		return KErrArgument;

		}

	// TO DO: De-stall the endpoint here.

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::EndpointStallStatus(TInt aRealEndpoint) const

//

// Reports the stall status of an endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::EndpointStallStatus(%d)", aRealEndpoint));

	if (IS_ISO_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Iso endpoint has no stall status"));

		return KErrArgument;

		}

	// TO DO: Query endpoint stall status here. The return value should reflect the actual state.

	return ETrue;

	}

TInt TTemplateAsspUsbcc::EndpointErrorStatus(TInt aRealEndpoint) const

//

// Reports the error status of an endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::EndpointErrorStatus(%d)", aRealEndpoint));

	if (!IS_VALID_ENDPOINT(aRealEndpoint))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: !IS_VALID_ENDPOINT(%d)", aRealEndpoint));

		return KErrArgument;

		}

	// TO DO: Query endpoint error status here. The return value should reflect the actual state.

	// With some UDCs there is no way of inquiring the endpoint error status; say 'ETrue' in that case.

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::ResetDataToggle(TInt aRealEndpoint)

//

// Resets to zero the data toggle bit of an endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::ResetDataToggle(%d)", aRealEndpoint));

	// TO DO: Reset the endpoint's data toggle bit here.

	// With some UDCs there is no way to individually reset the endpoint's toggle bits; just return KErrNone

	// in that case.

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::SynchFrameNumber() const

//

// For use with isochronous endpoints only. Causes the SOF frame number to be returned.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SynchFrameNumber"));

	// TO DO: Query and return the SOF frame number here.

	return 0;

	}

void TTemplateAsspUsbcc::SetSynchFrameNumber(TInt aFrameNumber)

//

// For use with isochronous endpoints only. Causes the SOF frame number to be stored.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SetSynchFrameNumber(%d)", aFrameNumber));

	// We should actually store this number somewhere. But the PIL always sends '0x00'

	// in response to a SYNCH_FRAME request...

	// TO DO: Store the frame number. Alternatively (until SYNCH_FRAME request specification changes): Do

	// nothing.

	}

TInt TTemplateAsspUsbcc::StartUdc()

//

// Called to initialize the device controller hardware before any operation can be performed.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::StartUdc"));

	if (iInitialized)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: UDC already initialised"));

		return KErrNone;

		}

	// Disable UDC (might also reset the entire design):

	UdcDisable();

	// Enable UDC's clock:

	// TO DO: Enable UDC's clock here.

	// Even if only one USB feature has been enabled, we later need to undo it:

	iInitialized = ETrue;

	// Bind & enable the UDC interrupt

	if (SetupUdcInterrupt() != KErrNone)

		{

		return KErrGeneral;

		}

	// Write meaningful values to some registers:

	InitialiseUdcRegisters();

	// Finally, turn on the UDC:

	UdcEnable();

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::StopUdc()

//

// Basically, makes undone what happened in StartUdc.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::StopUdc"));

	if (!iInitialized)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: UDC not initialized"));

		return KErrNone;

		}

	// Disable UDC:

	UdcDisable();

	// Mask (disable) Reset interrupt:

	// TO DO: Mask (disable) the USB Reset interrupt here.

	// Disable & unbind the UDC interrupt:

	ReleaseUdcInterrupt();

	// Finally turn off UDC's clock:

	// TO DO: Disable UDC's clock here.

	// Only when all USB features have been disabled we'll call it a day:

	iInitialized = EFalse;

	return KErrNone;

	}

TInt TTemplateAsspUsbcc::UdcConnect()

//

// Connects the UDC to the bus under software control. How this is achieved depends on the UDC; the

// functionality might also be part of the Variant component (instead of the ASSP).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::UdcConnect"));

	// Here: A call into the Variant-provided function.

	return iAssp->UsbConnect();

	}

TInt TTemplateAsspUsbcc::UdcDisconnect()

//

// Disconnects the UDC from the bus under software control. How this is achieved depends on the UDC; the

// functionality might also be part of the Variant component (instead of the ASSP).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::UdcDisconnect"));

	// Here: A call into the Variant-provided function.

	return iAssp->UsbDisconnect();

	}

TBool TTemplateAsspUsbcc::UsbConnectionStatus() const

//

// Returns a value showing the USB cable connection status of the device.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::UsbConnectionStatus"));

	return iCableConnected;

	}

TBool TTemplateAsspUsbcc::UsbPowerStatus() const

//

// Returns a truth value showing whether VBUS is currently powered or not.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::UsbPowerStatus"));

	return iBusIsPowered;

	}

TBool TTemplateAsspUsbcc::DeviceSelfPowered() const

//

// Returns a truth value showing whether the device is currently self-powered or not.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::DeviceSelfPowered"));

	// TO DO: Query and return self powered status here. The return value should reflect the actual state.

	// (This can be always 'ETrue' if the UDC does not support bus-powered devices.)

	return ETrue;

	}

const TUsbcEndpointCaps* TTemplateAsspUsbcc::DeviceEndpointCaps() const

//

// Returns a pointer to an array of elements, each of which describes the capabilities of one endpoint.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::DeviceEndpointCaps"));

	__KTRACE_OPT(KUSB, Kern::Printf(" > Ep: Sizes Mask, Types Mask"));

	__KTRACE_OPT(KUSB, Kern::Printf(" > --------------------------"));

	for (TInt i = 0; i < KUsbTotalEndpoints; ++i)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" > %02d: 0x%08x, 0x%08x",

										i, DeviceEndpoints[i].iSizes, DeviceEndpoints[i].iTypesAndDir));

		}

	return DeviceEndpoints;

	}

TInt TTemplateAsspUsbcc::DeviceTotalEndpoints() const

//

// Returns the element number of the endpoints array a pointer to which is returned by DeviceEndpointCaps.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::DeviceTotalEndpoints"));

	return KUsbTotalEndpoints;

	}

TBool TTemplateAsspUsbcc::SoftConnectCaps() const

//

// Returns a truth value showing whether or not there is the capability to disconnect and re-connect the D+

// line under software control.

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::SoftConnectCaps"));

	return iSoftwareConnectable;

	}

void TTemplateAsspUsbcc::Suspend()

//

// Called by the PIL after a Suspend event has been reported (by us).

//

	{

	__KTRACE_OPT(KUSB, Kern::Printf("TTemplateAsspUsbcc::Suspend"));

	// TO DO (optional): Implement here anything the device might require after bus SUSPEND signalling.

	}

void TTemplateAsspUsbcc::Resume()