// 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/drivers/usbcc/ps_usbc.cpp

// Platform independent layer (PIL) of the USB Device controller driver (PDD).

// Interface to the USB LDD.

// 

//

/**

 @file ps_usbc.cpp

 @internalTechnology

*/

#include <drivers/usbc.h>

/**

	TUsbcInterfaceSet and TUsbcInterface

	====================================

	TUsbcInterfaceSet represents a 'USB Interface' and TUsbcInterface

	represents an 'Alternate Setting of a USB Interface'.

	Since every LDD governs exactly one interface, the above distinction is

	made only within the USB implementation. At the LDD API, there is/are

	simply one or more settings for this single interface, numbered from '0'

	(the default) to 'n', and specified by the parameter 'TInt aInterfaceNum'.

	Within the PDD implementation, for a TUsbcInterfaceSet number the parameter

	'TInt aIfcSet' is used (local variable ifcset); for a TUsbcInterface number

	the parameter 'TInt aIfc' is used (local variable ifc).

	iConfigs[0] and CurrentConfig()

	===============================

	One problem with this file is that it always uses iConfigs[0] and not

	CurrentConfig(). This is mainly because the API to the LDD doesn't know

	about the concept of multiple configurations, and thus always assumes one

	single configuration (which is also always active: a further problem).

	In the file chapter9.cpp this issue doesn't exist, since there we always

	have to obey the USB protocol, and in this way will use the configuration

	which is selected by the host (which will then again currently always be

	iConfigs[0].)

	iEp0ClientId and iEp0DataReceiving

	==================================

	The purpose of these two members of class DUsbClientController is the

	following.

	They are used only during Ep0 control transactions which have an OUT (Rx)

	data stage. The special problem with these transactions is twofold. For one

	thing we have to know that what we are receiving is data and not a Setup

	packet. Furthermore we cannot deduce from the received data itself to whom

	it is addressed (that's because of the shared nature of Ep0).

	So in order to recognize data packets we use iEp0DataReceiving. This

	variable is set to TRUE either 1) upon processing a standard request which

	has a DATA_OUT phase (only SET_DESCRIPTOR), or 2) if we have identified a

	class-specific request which has a DATA_OUT phase and we have also found

	the recipient for that request.

	In order to be able to tell whether received Ep0 data is to be processed by

	the PIL or a LDD, we use iEp0ClientId. iEp0ClientId is usually NULL, which

	means it is our data. However it is set to the client ID of an LDD in case

	2) above. That way we can subsequently hand over received data to the

	correct client LDD.

	iEp0DataReceived tracks the amount of data already received - it is used to

	determine the end of the DATA_OUT phase, irrespective of the owner of the

	data. The total amount that is to be received can be obtained via

	iSetup.iLength. (iSetup holds in that case the Setup packet of the current

	Control transfer.)

	iEp0ClientDataTransmitting is only set to TRUE if a client sets up an Ep0

	write. After that transmission has completed we use this value to decide

	whether we have to report the completion to a client or not. (If this

	variable is FALSE, we did set up the write and thus no client notification

	is necessary.)

*/

//

// === Global and Local Variables ==================================================================

//

GLDEF_D DUsbClientController* DUsbClientController::UsbClientController[] = {NULL, NULL};

static const TInt KUsbReconnectDelay   = 500;				// milliseconds

static const TInt KUsbCableStatusDelay = 500;				// milliseconds

//

// === USB Controller member function implementations - LDD API (public) ===========================

//

/** The class destructor.

	This rarely gets called, except, for example when something goes

	wrong during construction.

	It's not exported because it is virtual.

*/

DUsbClientController::~DUsbClientController()

	{

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

	if (iPowerHandler)

		{

		iPowerHandler->Remove();

		delete iPowerHandler;

		}

	// ResetAndDestroy() will call for every array element the destructor of the pointed-to object,

	// before deleting the element itself, and closing the array.

	iConfigs.ResetAndDestroy();

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::~DUsbClientController(): Done."));

	}

/** To be called by the OTG/Host stack in an OTG setup to disable USB device

	functionality.

	The OTG stack calls this function when VBus is no longer valid, when the

	B-device swaps out of peripheral mode, or when moving out of the

	A_PERIPHERAL state.

	The Client stack will disable the D+ pull-up immediately when the function

	is called.

	During DisableClientStack() the Client stack will notify its registered

	applications on the user-side (including the USB Manager) about a USB

	device state change event, a transition to the "Undefined" state.

*/

EXPORT_C void DUsbClientController::DisableClientStack()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DisableClientStack()"));

	if (!iStackIsActive)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Already disabled - returning"));

		return;

		}

	iOtgClientConnect = EFalse;

	TInt r = EvaluateOtgConnectFlags();					 // will disconnect UDC

	if (r != KErrNone)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: EvaluateOtgConnectFlags() failed: %d", r));

		}

	// Reset OTG features, leave attributes as is (just as in USB Reset case)

	// (OTG spec 1.3 sections 6.5.x all say "... on a bus reset or at the end

	//  of a session." VBus drop is the end of a session.)

	iOtgFuncMap &= KUsbOtgAttr_SrpSupp | KUsbOtgAttr_HnpSupp;

	OtgFeaturesNotify();

	// Tear down the current configuration (if any)

	ChangeConfiguration(0);

	if (iDeviceState != EUsbcDeviceStateUndefined)

		{

		// Not being in state UNDEFINED implies that the cable is inserted.

		if (iHardwareActivated)

			{

			NextDeviceState(EUsbcDeviceStatePowered);

			}

		// (If the hardware is NOT activated at this point, we can only be in

		//	state EUsbcDeviceStateAttached, so we don't have to move to it.)

		}

	DeActivateHardwareController();					 // turn off UDC altogether

	iStackIsActive = EFalse;

	// Complete all pending requests, returning KErrDisconnected

	RunClientCallbacks();

	// Notify registered clients on the user side about a USB device state

	// change event and a transition to the "Undefined" state.

	NextDeviceState(EUsbcDeviceStateUndefined);

	}

/** To be called by the OTG/Host stack in an OTG setup to enable USB device

	functionality.

	Once called, the function will return quickly, but it will by then not

	necessarily have enabled the D+ pull-up*. The Client stack can enable the D+

	pull-up (via the transceiver) from that moment on and as long as the OTG

	stack doesn't call DisableClientStack().

	*) It will enable the D+ pull-up immediately if the user-side USB support

	has already been loaded. This should always be the case when the OTG stack

	is calling this function during the transition to the A_PERIPHERAL state,

	i.e. when acting as an A-device.

*/

EXPORT_C void DUsbClientController::EnableClientStack()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::EnableClientStack()"));

	if (iStackIsActive)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Already enabled - returning"));

		return;

		}

	iStackIsActive = ETrue;

	// If the UDC is still off, we switch it on here.

	TInt r = ActivateHardwareController();

	if (r != KErrNone)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: ActivateHardwareController() failed: %d", r));

		}

	iOtgClientConnect = ETrue;

	r = EvaluateOtgConnectFlags();							// may connect UDC

	if (r != KErrNone)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: EvaluateOtgConnectFlags() failed: %d", r));

		}

	}

/** Called by LDD to see if controller is usable.

	@return ETrue if controller is in normal state, EFalse if it is disabled.

*/

EXPORT_C TBool DUsbClientController::IsActive()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::IsActive()"));

	return iStackIsActive;

	}

/** Called by LDD to register client callbacks.

	@return KErrNone if successful, KErrAlreadyExists callback exists.

*/

EXPORT_C TInt DUsbClientController::RegisterClientCallback(TUsbcClientCallback& aCallback)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::RegisterClientCallback()"));

	if (iClientCallbacks.Elements() == KUsbcMaxListLength)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Maximum list length reached: %d",

										  KUsbcMaxListLength));

		return KErrGeneral;

		}

	TSglQueIter<TUsbcClientCallback> iter(iClientCallbacks);

	TUsbcClientCallback* p;

	while ((p = iter++) != NULL)

		if (p == &aCallback)

			{

			__KTRACE_OPT(KUSB, Kern::Printf("	 Error: ClientCallback @ 0x%x already registered", &aCallback));

			return KErrAlreadyExists;

			}

	iClientCallbacks.AddLast(aCallback);

	return KErrNone;

	}

/** Returns a pointer to the USB client controller object.

	This function is static.

	@param aUdc The number of the UDC (0..n) for which the pointer is to be returned.

	@return A pointer to the USB client controller object.

*/

EXPORT_C DUsbClientController* DUsbClientController::UsbcControllerPointer(TInt aUdc)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::UsbcControllerPointer()"));

	if (aUdc < 0 || aUdc > 1)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: aUdc out of range (%d)", aUdc));

		return NULL;

		}

	return UsbClientController[aUdc];

	}

/** Fills the buffer passed in as an argument with endpoint capability information.

 	@see DUsbClientController::DeviceCaps()

	@see TUsbcEndpointData

	@see TUsbDeviceCaps

	@param aClientId A pointer to the LDD making the enquiry.

	@param aCapsBuf A reference to a descriptor buffer, which, on return, contains an array of

	TUsbcEndpointData elements; there are TUsbDeviceCaps::iTotalEndpoints elements in the array;

	call DeviceCaps() to get the number of elements required.

*/

EXPORT_C void DUsbClientController::EndpointCaps(const DBase* aClientId, TDes8& aCapsBuf) const

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::EndpointCaps()"));

	// Here we do not simply call DUsbClientController::DeviceEndpointCaps(),

	// because that function fills an array which comprises of _all_ endpoints,

	// whereas this function omits ep0 and all unusable endpoints.

	// Apart from that, we have to fill an array of TUsbcEndpointData, not TUsbcEndpointCaps.

	TUsbcEndpointData data[KUsbcMaxEndpoints];

	const TInt ifcset_num = ClientId2InterfaceNumber(aClientId);

	for (TInt i = 2, j = 0; i < iDeviceTotalEndpoints; ++i)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::Caps: RealEndpoint #%d", i));

		if (iRealEndpoints[i].iCaps.iTypesAndDir != KUsbEpNotAvailable)

			{

			__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::Caps: --> UsableEndpoint #%d", j));

			data[j].iCaps = iRealEndpoints[i].iCaps;

			if (ifcset_num < 0)

				{

				// If this LDD doesn't own an interface, but the Ep points to one,

				// then that must be the interface of a different LDD. Hence the Ep

				// is not available for this LDD.

				data[j].iInUse = (iRealEndpoints[i].iIfcNumber != NULL);

				}

			else

				{

				// If this LDD does already own an interface, and the Ep also points to one,

				// then the Ep is not available for this LDD only if that interface is owned

				// by a different LDD (i.e. if the interface number is different).

				// Reason: Even though the endpoint might already be part of an interface setting,

				// it is still available for a different alternate setting of the same interface.

				data[j].iInUse = ((iRealEndpoints[i].iIfcNumber != NULL) &&

								  (*(iRealEndpoints[i].iIfcNumber) != ifcset_num));

				}

			j++;

			}

		}

	// aCapsBuf resides in userland

	TPtrC8 des((TUint8*)data, sizeof(data));

	const TInt r = Kern::ThreadDesWrite((reinterpret_cast<const DLddUsbcChannel*>(aClientId))->Client(),

										&aCapsBuf, des, 0, KChunkShiftBy0, NULL);

	if (r != KErrNone)

		{

		Kern::ThreadKill((reinterpret_cast<const DLddUsbcChannel*>(aClientId))->Client(),

						 EExitPanic, r, KUsbPILKillCat);

		}

	}

/** Fills the buffer passed in as an argument with device capability information.

	@see TUsbDeviceCaps

	@see TUsbDeviceCapsV01

	@param aClientId A pointer to the LDD making the enquiry.

	@param aCapsBuf A reference to a descriptor buffer which, on return, contains

	a TUsbDeviceCaps structure.

*/

EXPORT_C void DUsbClientController::DeviceCaps(const DBase* aClientId, TDes8& aCapsBuf) const

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DeviceCaps()"));

	TUsbDeviceCaps caps;

	caps().iTotalEndpoints = iDeviceUsableEndpoints;		// not DeviceTotalEndpoints()!

	caps().iConnect = SoftConnectCaps();

	caps().iSelfPowered = iSelfPowered;

	caps().iRemoteWakeup = iRemoteWakeup;

	caps().iHighSpeed = DeviceHighSpeedCaps();

	caps().iFeatureWord1 = CableDetectWithoutPowerCaps() ?

		caps().iFeatureWord1 | KUsbDevCapsFeatureWord1_CableDetectWithoutPower :

		caps().iFeatureWord1 & ~KUsbDevCapsFeatureWord1_CableDetectWithoutPower;

	caps().iFeatureWord1 = DeviceResourceAllocV2Caps() ?

		caps().iFeatureWord1 | KUsbDevCapsFeatureWord1_EndpointResourceAllocV2 :

		caps().iFeatureWord1 & ~KUsbDevCapsFeatureWord1_EndpointResourceAllocV2;

	caps().iReserved = 0;

	// aCapsBuf resides in userland

	const TInt r = Kern::ThreadDesWrite((reinterpret_cast<const DLddUsbcChannel*>(aClientId))->Client(),

										&aCapsBuf, caps, 0, KChunkShiftBy0, NULL);

	if (r != KErrNone)

		{

		Kern::ThreadKill((reinterpret_cast<const DLddUsbcChannel*>(aClientId))->Client(),

						 EExitPanic, r, KUsbPILKillCat);

		}

	}

TUsbcEndpointInfoArray::TUsbcEndpointInfoArray(const TUsbcEndpointInfo* aData, TInt aDataSize)

	{

	iType = EUsbcEndpointInfo;

	iData = (TUint8*) aData;

	if (aDataSize > 0)

		iDataSize = aDataSize;

	else

		iDataSize = sizeof(TUsbcEndpointInfo);

	}

inline TUsbcEndpointInfo& TUsbcEndpointInfoArray::operator[](TInt aIndex) const

	{

	return *(TUsbcEndpointInfo*) &iData[aIndex * iDataSize];

	}

EXPORT_C TInt DUsbClientController::SetInterface(const DBase* aClientId, DThread* aThread,

												 TInt aInterfaceNum, TUsbcClassInfo& aClass,

												 TDesC8* aString, TInt aTotalEndpointsUsed,

												 const TUsbcEndpointInfo aEndpointData[],

												 TInt (*aRealEpNumbers)[6], TUint32 aFeatureWord)

	{

	TUsbcEndpointInfoArray endpointData = TUsbcEndpointInfoArray(aEndpointData);

	return SetInterface(aClientId, aThread, aInterfaceNum, aClass, aString, aTotalEndpointsUsed,

						endpointData, (TInt*) aRealEpNumbers, aFeatureWord);

	}

/** Creates a new USB interface (one setting), complete with endpoints, descriptors, etc.,

	and chains it into the internal device configuration tree.

	@param aClientId A pointer to the LDD owning the new interface.

	@param aThread A pointer to the thread the owning LDD is running in.

	@param aInterfaceNum The interface setting number of the new interface setting. This must be 0

	if it is the first setting of the interface that gets created, or 1 more than the last setting

	that was created for this interface.

	@param aClass Contains information about the device class this interface might belong to.

	@param aString A pointer to a string that is used for the string descriptor of this interface.

	@param aTotalEndpointsUsed The number of endpoints used by this interface (and also the number of

	elements of the following array).

	@param aEndpointData An array with aTotalEndpointsUsed elements, containing information about the

	endpoints of this interface.

	@return KErrNotSupported if Control endpoints are requested by the LDD but aren't supported by the PIL,

	KErrInUse if at least one requested endpoint is - temporarily or permanently - not available for use,

	KErrNoMemory if (endpoint, interface, string) descriptor allocation fails, KErrGeneral if something else

	goes wrong during endpoint or interface or descriptor creation, KErrNone if interface successfully set up.

*/

EXPORT_C TInt DUsbClientController::SetInterface(const DBase* aClientId, DThread* aThread,

												 TInt aInterfaceNum, TUsbcClassInfo& aClass,

												 TDesC8* aString, TInt aTotalEndpointsUsed,

												 const TUsbcEndpointInfoArray aEndpointData,

												 TInt aRealEpNumbers[], TUint32 aFeatureWord)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::SetInterface()"));

	if (aInterfaceNum != 0)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  alternate interface setting request: #%d", aInterfaceNum));

		}

#ifndef USB_SUPPORTS_CONTROLENDPOINTS

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

		{

		if (aEndpointData[i].iType == KUsbEpTypeControl)

			{

			__KTRACE_OPT(KPANIC, Kern::Printf("  Error: control endpoints not supported"));

			return KErrNotSupported;

			}

		}

#endif

	// Check for endpoint availability & check those endpoint's capabilities

	const TInt ifcset_num = ClientId2InterfaceNumber(aClientId);

	// The passed-in ifcset_num may be -1 now, but that's intended.

	if (!CheckEpAvailability(aTotalEndpointsUsed, aEndpointData, ifcset_num))

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: endpoints not (all) available"));

		return KErrInUse;

		}

	// Create & setup new interface

	TUsbcInterface* ifc = CreateInterface(aClientId, aInterfaceNum, aFeatureWord);

	if (ifc == NULL)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: ifc == NULL"));

		return KErrGeneral;

		}

	// Create logical endpoints

	TInt r = CreateEndpoints(ifc, aTotalEndpointsUsed, aEndpointData, aRealEpNumbers);

	if (r != KErrNone)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: CreateEndpoints() != KErrNone"));

		DeleteInterface(ifc->iInterfaceSet->iInterfaceNumber, aInterfaceNum);

		return r;

		}

	// Create & setup interface, string, and endpoint descriptors

	r = SetupIfcDescriptor(ifc, aClass, aThread, aString, aEndpointData);

	if (r != KErrNone)

		{

		return r;

		}

	return KErrNone;

	}

/** Releases an existing USB interface (one setting), complete with endpoints, descriptors, etc.,

	and removes it from the internal device configuration tree.

	@param aClientId A pointer to the LDD owning the interface.

	@param aInterfaceNum The setting number of the interface setting to be deleted. This must be

	the highest numbered (or 'last') setting for this interface.

	@return KErrNotFound if interface (not setting) for some reason cannot be found, KErrArgument if an

	invalid interface setting number is specified (not existing or existing but too small), KErrNone if

	interface successfully released or if this client doesn't own any interface.

*/

EXPORT_C TInt DUsbClientController::ReleaseInterface(const DBase* aClientId, TInt aInterfaceNum)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::ReleaseInterface(..., %d)", aInterfaceNum));

	const TInt ifcset = ClientId2InterfaceNumber(aClientId);

	if (ifcset < 0)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" interface not found")); // no error

		return KErrNone;

		}

	TUsbcInterfaceSet* const ifcset_ptr = InterfaceNumber2InterfacePointer(ifcset);

	if (!ifcset_ptr)

		{

		__KTRACE_OPT(KUSB, Kern::Printf(" Error: interface number %d doesn't exist", ifcset));

		return KErrNotFound;

		}

	const TInt setting_count = ifcset_ptr->iInterfaces.Count();

	if ((setting_count - 1) != aInterfaceNum)

		{

		__KTRACE_OPT(KUSB,

					 Kern::Printf(" > Error: interface settings must be released in descending order:\n\r"

								  "   %d setting(s) exist, #%d was requested to be released.\n\r"

								  "   (#%d has to be released first)",

								  setting_count, aInterfaceNum, setting_count - 1));

		return KErrArgument;

		}

	// Tear down current setting (invalidate configured state)

	__KTRACE_OPT(KUSB, Kern::Printf(" > tearing down InterfaceSet %d", ifcset));

	// Cancel all transfers on the current setting of this interface and deconfigure all its endpoints.

	InterfaceSetTeardown(ifcset_ptr);

	// 'Setting 0' means: delete all existing settings.

	if (aInterfaceNum == 0)

		{

		TInt m = ifcset_ptr->iInterfaces.Count();

		while (m > 0)

			{

			m--;

			// Ground the physical endpoints' logical_endpoint_pointers

			const TInt n = ifcset_ptr->iInterfaces[m]->iEndpoints.Count();

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

				{

				TUsbcPhysicalEndpoint* ptr = const_cast<TUsbcPhysicalEndpoint*>

					(ifcset_ptr->iInterfaces[m]->iEndpoints[i]->iPEndpoint);

				ptr->iLEndpoint = NULL;

				}

			// Delete the setting itself + its ifc & ep descriptors

			DeleteInterface(ifcset, m);

			iDescriptors.DeleteIfcDescriptor(ifcset, m);

			}

		}

	else

		{

		// Ground the physical endpoints' logical_endpoint_pointers

		const TInt n = ifcset_ptr->iInterfaces[aInterfaceNum]->iEndpoints.Count();

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

			{

			TUsbcPhysicalEndpoint* ptr = const_cast<TUsbcPhysicalEndpoint*>

				(ifcset_ptr->iInterfaces[aInterfaceNum]->iEndpoints[i]->iPEndpoint);

			ptr->iLEndpoint = NULL;

			}

		// Delete the setting itself + its ifc & ep descriptors

		DeleteInterface(ifcset, aInterfaceNum);

		iDescriptors.DeleteIfcDescriptor(ifcset, aInterfaceNum);

		}

	// Delete the whole interface if all settings are gone

	if (ifcset_ptr->iInterfaces.Count() == 0)

		{

		DeleteInterfaceSet(ifcset);

		}

	// We now no longer have a valid current configuration

	iCurrentConfig = 0;

	if (iDeviceState == EUsbcDeviceStateConfigured)

		{

		NextDeviceState(EUsbcDeviceStateAddress);

		}

	// If it was the last interface(set)...

	if (iConfigs[0]->iInterfaceSets.Count() == 0)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  No ifc left -> turning off UDC"));

		// First disconnect the device from the bus

		UsbDisconnect();

		DeActivateHardwareController();

		// (this also disables endpoint zero; we cannot have a USB device w/o interface, see 9.6.3)

		}

	return KErrNone;

	}

/** Enforces a USB re-enumeration by disconnecting the UDC from the bus (if it is currently connected) and

	re-connecting it.

	This only works if the PSL supports it, i.e. if SoftConnectCaps() returns ETrue.

*/

EXPORT_C TInt DUsbClientController::ReEnumerate()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::ReEnumerate()"));

	// If, in an OTG setup, the client stack is disabled, there's no point in

	// trying to reenumerate the device. In fact, we then don't even want to

	// turn on the UDC via ActivateHardwareController().

	if (!iStackIsActive)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Client stack disabled -> returning here"));

		return KErrNotReady;

		}

	// We probably don't check here whether SoftConnectCaps() is ETrue, and

	// return if not, because we might still want to execute

	// ActivateHardwareController(). UsbConnect() and UsbDisconnect() should be

	// no-ops if not supported by the PSL.

	if (iConfigs[0]->iInterfaceSets.Count() == 0)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  > No interface registered -> no need to re-enumerate"));

		return KErrNone;;

		}

	if (!iHardwareActivated)

		{

		// If the UDC is still off, we switch it on here.

		const TInt r = ActivateHardwareController();

		if (r != KErrNone)

				{

				__KTRACE_OPT(KPANIC, Kern::Printf("  Error: ActivateHardwareController() failed: %d", r));

				return r;

				}

		// Finally connect the device to the bus

		UsbConnect();

		}

	else

		{

		UsbDisconnect();

		// Now we have to wait a certain amount of time, in order to give the host the opportunity

		// to come to terms with the new situation.

		// (The ETrue parameter makes the callback get called in DFC instead of in ISR context.)

		iReconnectTimer.OneShot(KUsbReconnectDelay, ETrue);

		}

	return KErrNone;;

	}

/** Powers up the UDC if one or more interfaces exist.

	@return KErrNone if UDC successfully powered up, KErrNotReady if no

	interfaces have been registered yet, KErrHardwareNotAvailable if UDC

	couldn't be activated.

*/

EXPORT_C TInt DUsbClientController::PowerUpUdc()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::PowerUpUdc()"));

	// If, in an OTG setup, the client stack is disabled, we mustn't turn on

	// the UDC via ActivateHardwareController() as that would already configure

	// Ep0.

	if (!iStackIsActive)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Client stack disabled -> returning here"));

		return KErrNotReady;

		}

	if (iConfigs[0]->iInterfaceSets.Count() == 0)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  > No interface registered -> won't power up UDC"));

		return KErrNotReady;

		}

	// If the UDC is still off, we switch it on here.

	const TInt r = ActivateHardwareController();

	if (r != KErrNone)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: ActivateHardwareController() failed: %d", r));

		}

	return r;

	}

/** Connects the UDC to the bus.

	This only works if the PSL supports it, i.e. if SoftConnectCaps() returns ETrue.

	@return KErrNone if UDC successfully connected, KErrGeneral if there was an error.

*/

EXPORT_C TInt DUsbClientController::UsbConnect()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::UsbConnect()"));

#ifdef USB_OTG_CLIENT

	iClientSupportReady = ETrue;

	const TInt r = EvaluateOtgConnectFlags();

	const TInt irq = NKern::DisableAllInterrupts();

	if (iUsbResetDeferred) // implies (iOtgHnpHandledByHw == ETrue)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Resetting USB Reset 'defer' flag"));

		iUsbResetDeferred = EFalse;

		(void) ProcessResetEvent(EFalse);

		}

	NKern::RestoreInterrupts(irq);

#else

	const TInt r = UdcConnect();

#endif // USB_OTG_CLIENT

	return r;

	}

/** Disconnects the UDC from the bus.

	This only works if the PSL supports it, i.e. if SoftConnectCaps() returns ETrue.

	@return KErrNone if UDC successfully disconnected, KErrGeneral if there was an error.

*/

EXPORT_C TInt DUsbClientController::UsbDisconnect()

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::UsbDisconnect()"));

#ifdef USB_OTG_CLIENT

	iClientSupportReady = EFalse;

	const TInt r = EvaluateOtgConnectFlags();

#else

	const TInt r = UdcDisconnect();

#endif // USB_OTG_CLIENT

	// There won't be any notification by the PSL about this,

	// so we have to notify the LDD/user ourselves:

	if ((r == KErrNone) && (iDeviceState != EUsbcDeviceStateUndefined))

		{

		// Not being in state UNDEFINED implies that the cable is inserted.

		if (iHardwareActivated)

			{

			NextDeviceState(EUsbcDeviceStatePowered);

			}

		// (If the hardware is NOT activated at this point, we can only be in

		//	state EUsbcDeviceStateAttached, so we don't have to move to it.)

		}

	return r;

	}

/** Registers a notification callback for changes of the USB device state.

	In the event of a device state change, the callback's state member gets updated (using SetState) with a

	new TUsbcDeviceState value, and then the callback is executed (DoCallback). 'USB device state' here refers

	to the Visible Device States as defined in chapter 9 of the USB specification.

	@param aCallback A reference to a properly filled in status callback structure.

	@return KErrNone if callback successfully registered, KErrGeneral if this callback is already registered

	(it won't be registered twice).

*/

EXPORT_C TInt DUsbClientController::RegisterForStatusChange(TUsbcStatusCallback& aCallback)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::RegisterForStatusChange()"));

	if (iStatusCallbacks.Elements() == KUsbcMaxListLength)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Maximum list length reached: %d",

										  KUsbcMaxListLength));

		return KErrGeneral;

		}

	if (IsInTheStatusList(aCallback))

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Error: StatusCallback @ 0x%x already registered", &aCallback));

		return KErrGeneral;

		}

	const TInt irq = NKern::DisableAllInterrupts();

	iStatusCallbacks.AddLast(aCallback);

	NKern::RestoreInterrupts(irq);

	return KErrNone;

	}

/** De-registers (removes from the list of pending requests) a notification callback for the USB device

	status.

	@param aClientId A pointer to the LDD owning the status change callback.

	@return KErrNone if callback successfully unregistered, KErrNotFound if the callback couldn't be found.

*/

EXPORT_C TInt DUsbClientController::DeRegisterForStatusChange(const DBase* aClientId)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DeRegisterForStatusChange()"));

	__ASSERT_DEBUG((aClientId != NULL), Kern::Fault(KUsbPILPanicCat, __LINE__));

	const TInt irq = NKern::DisableAllInterrupts();

	TSglQueIter<TUsbcStatusCallback> iter(iStatusCallbacks);

	TUsbcStatusCallback* p;

	while ((p = iter++) != NULL)

		{

		if (p->Owner() == aClientId)

			{

			__KTRACE_OPT(KUSB, Kern::Printf("  removing StatusCallback @ 0x%x", p));

			iStatusCallbacks.Remove(*p);

			NKern::RestoreInterrupts(irq);

			return KErrNone;

			}

		}

	__KTRACE_OPT(KUSB, Kern::Printf("  client not found"));

	NKern::RestoreInterrupts(irq);

	return KErrNotFound;

	}

/** Registers a notification callback for changes of the state of endpoints.

	In the event of a state change of an endpoint that is spart of an interface which is owned by the LDD

	specified in the callback structure, the callback's state member gets updated (using SetState) with a new

	value, and the callback is executed (DoCallback). 'Endpoint state' here refers to the state of the

	ENDPOINT_HALT feature of an endpoint as described in chapter 9 of the USB specification. The contents of

	the state variable reflects the state of the halt features for all endpoints of the current interface

	setting: bit 0 represents endpoint 1, bit 1 endpoint 2, etc. A set bit means 'endpoint halted', a cleared

	bit 'endpoint not halted'.

	@param aCallback A reference to a properly filled in endpoint status callback structure.

	@return KErrNone if callback successfully registered, KErrGeneral if this callback is already registered

	(it won't be registered twice).

*/

EXPORT_C TInt DUsbClientController::RegisterForEndpointStatusChange(TUsbcEndpointStatusCallback& aCallback)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::RegisterForEndpointStatusChange()"));

	if (iEpStatusCallbacks.Elements() == KUsbcMaxListLength)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: Maximum list length reached: %d",

										  KUsbcMaxListLength));

		return KErrGeneral;

		}

	if (IsInTheEpStatusList(aCallback))

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Error: EpStatusCallback @ 0x%x already registered", &aCallback));

		return KErrGeneral;

		}

	const TInt irq = NKern::DisableAllInterrupts();

	iEpStatusCallbacks.AddLast(aCallback);

	NKern::RestoreInterrupts(irq);

	return KErrNone;

	}

/** De-registers (removes from the list of pending requests) a notification callback for changes of the state

	of endpoints.

	@param aClientId A pointer to the LDD owning the endpoint status change callback.

	@return KErrNone if callback successfully unregistered, KErrNotFound if the callback couldn't be found.

*/

EXPORT_C TInt DUsbClientController::DeRegisterForEndpointStatusChange(const DBase* aClientId)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DeRegisterForEndpointStatusChange()"));

	__ASSERT_DEBUG((aClientId != NULL), Kern::Fault(KUsbPILPanicCat, __LINE__));

	const TInt irq = NKern::DisableAllInterrupts();

	TSglQueIter<TUsbcEndpointStatusCallback> iter(iEpStatusCallbacks);

	TUsbcEndpointStatusCallback* p;

	while ((p = iter++) != NULL)

		{

		if (p->Owner() == aClientId)

			{

			__KTRACE_OPT(KUSB, Kern::Printf("  removing EpStatusCallback @ 0x%x", p));

			iEpStatusCallbacks.Remove(*p);

			NKern::RestoreInterrupts(irq);

			return KErrNone;

			}

		}

	__KTRACE_OPT(KUSB, Kern::Printf("  client not found"));

	NKern::RestoreInterrupts(irq);

	return KErrNotFound;

	}

/** Returns the number of the currently active alternate interface setting for this interface.

	@param aClientId A pointer to the LDD owning the interface.

	@param aInterfaceNum Here the interface gets written to.

	@return KErrNotFound if an interface for this client couldn't be found, KErrNone if setting value was

	successfully written.

*/

EXPORT_C TInt DUsbClientController::GetInterfaceNumber(const DBase* aClientId, TInt& aInterfaceNum) const

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::GetInterfaceNumber()"));

	const TInt ifcset = ClientId2InterfaceNumber(aClientId);

	if (ifcset < 0)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error (ifc < 0)"));

		return KErrNotFound;

		}

	const TUsbcInterfaceSet* const ifcset_ptr = InterfaceNumber2InterfacePointer(ifcset);

	if (!ifcset_ptr)

		{

		__KTRACE_OPT(KPANIC, Kern::Printf("  Error: interface number %d doesn't exist", ifcset));

		return KErrNotFound;

		}

	aInterfaceNum = ifcset_ptr->iCurrentInterface;

	return KErrNone;

	}

/** This is normally called once by an LDD's destructor, either after a Close() on the user side,

	or during general cleanup.

	It might also be called by the LDD when some internal unrecoverable error occurs.

	This function

	- de-registers a possibly pending device state change notification request,

	- de-registers a possibly pending endpoint state change notification request,

	- releases all interfaces + settings owned by this LDD,

	- cancels all remaining (if any) read/write requests.

	@param aClientId A pointer to the LDD to be unregistered.

	@return KErrNone.

*/

EXPORT_C TInt DUsbClientController::DeRegisterClient(const DBase* aClientId)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DeRegisterClient(0x%x)", aClientId));

	// Cancel all device state notification requests

	DeRegisterForStatusChange(aClientId);

	// Cancel all endpoint state notification requests

	DeRegisterForEndpointStatusChange(aClientId);

	DeRegisterForOtgFeatureChange(aClientId);

	DeRegisterClientCallback(aClientId);

	// Delete the interface including all its alternate settings which might exist.

	// (If we release the default setting (0), all alternate settings are deleted as well.)

	const TInt r = ReleaseInterface(aClientId, 0);

	// Cancel all remaining (if any) read/write requests

	DeleteRequestCallbacks(aClientId);

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::DeRegisterClient: Done."));

	return r;

	}

/** Returns the currently used Ep0 max packet size.

	@return The currently used Ep0 max packet size.

*/

EXPORT_C TInt DUsbClientController::Ep0PacketSize() const

	{

	const TUsbcLogicalEndpoint* const ep = iRealEndpoints[0].iLEndpoint;

	if (iHighSpeed)

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Ep0 size = %d (HS)", ep->iEpSize_Hs));

		return ep->iEpSize_Hs;

		}

	else

		{

		__KTRACE_OPT(KUSB, Kern::Printf("  Ep0 size = %d (FS)", ep->iEpSize_Fs));

		return ep->iEpSize_Fs;

		}

	}

/** Stalls Ep0.

	@param aClientId A pointer to the LDD wishing to stall Ep0 (this is for PIL internal purposes only).

	@return KErrNone if endpoint zero successfully stalled, KErrGeneral otherwise.

*/

EXPORT_C TInt DUsbClientController::Ep0Stall(const DBase* aClientId)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::Ep0Stall()"));

	if (aClientId == iEp0ClientId)

		{

		ResetEp0DataOutVars();

		}

	const TInt err = StallEndpoint(KEp0_Out);

	if (err < 0)

		{

		return err;

		}

	else

		return StallEndpoint(KEp0_In);

	}

/** Sends a zero-byte status packet on Ep0.

	@param aClientId A pointer to the LDD wishing to send the status packet (not used at present).

*/

EXPORT_C void DUsbClientController::SendEp0StatusPacket(const DBase* /* aClientId */)

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::SendEp0StatusPacket()"));

	SendEp0ZeroByteStatusPacket();

	}

/** Returns the current USB device state.

	'USB device state' here refers to the Visible Device States as defined in chapter 9 of the USB

	specification.

	@return The current USB device state, or EUsbcDeviceStateUndefined if the UDC doesn't allow device state

	tracking (PSL's DeviceStateChangeCaps() returns EFalse).

*/

EXPORT_C TUsbcDeviceState DUsbClientController::GetDeviceStatus() const

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::GetDeviceStatus()"));

	return iDeviceState;

	}

/** Returns the state of an endpoint.

	'Endpoint state' here refers to the state of the ENDPOINT_HALT feature of

	an endpoint as described in chapter 9 of the USB specification.

	@param aClientId A pointer to the LDD owning the interface which contains the endpoint to be queried.

	@param aEndpointNum The number of the endpoint to be queried.

	@return The current endpoint state, or EEndpointStateUnknown if the endpoint couldn't be found.

*/

EXPORT_C TEndpointState DUsbClientController::GetEndpointStatus(const DBase* aClientId, TInt aEndpointNum) const

	{

	__KTRACE_OPT(KUSB, Kern::Printf("DUsbClientController::GetEndpointStatus()"));

	return EndpointStallStatus(aEndpointNum) ?

		EEndpointStateStalled :