// Copyright (c) 2006-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\soundsc\soundldd.cpp

// LDD for the shared chunk sound driver.

// 

//

/**

 @file

 @internalTechnology

 @prototype

*/

#include <drivers/soundsc.h>

#include <kernel/kern_priv.h>

#include <kernel/cache.h>

//#define USE_PLAY_EOF_TIMER

// Define TEST_WITH_PAGING_CACHE_FLUSHES to flush the paging cache when testing read/writes to user thread in a data-paging system

//#define TEST_WITH_PAGING_CACHE_FLUSHES

static const char KSoundLddPanic[]="Sound LDD";

LOCAL_C TInt HighestCapabilitySupported(TUint32 aCapsBitField)

	{

	TInt n;

	for (n=31 ; n>=0 ; n--)

		{

		if (aCapsBitField&(1<<n))

			break;

		}

	return(n);

	}

/**

Standard export function for LDDs. This creates a DLogicalDevice derived object,

in this case, DSoundScLddFactory.

*/

DECLARE_STANDARD_LDD()

	{

	return new DSoundScLddFactory;

	}

/**

Constructor for the sound driver factory class.

*/

DSoundScLddFactory::DSoundScLddFactory()

	{

//	iUnitsOpenMask=0;

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLddFactory::DSoundScLddFactory"));

	// Set version number for this device.

	iVersion=RSoundSc::VersionRequired();

	// Indicate that units / PDD are supported.

	iParseMask=KDeviceAllowUnit|KDeviceAllowPhysicalDevice;

	// Leave the units decision to the PDD

	iUnitsMask=0xffffffff;

	}

/**

Second stage constructor for the sound driver factory class.

This must at least set a name for the driver object.

@return KErrNone if successful, otherwise one of the other system wide error codes.

*/

TInt DSoundScLddFactory::Install()

	{

	return(SetName(&KDevSoundScName));

	}

/**

Return the 'capabilities' of the sound driver in general.

Called in the response to an RDevice::GetCaps() request.

@param aDes A user-side descriptor to write the capabilities information into.

*/

void DSoundScLddFactory::GetCaps(TDes8& aDes) const

	{

	// Create a capabilities object

	TCapsSoundScV01 caps;

	caps.iVersion=iVersion;

	// Write it back to user memory

	Kern::InfoCopy(aDes,(TUint8*)&caps,sizeof(caps));

	}

/**

Called by the kernel's device driver framework to create a logical channel.

This is called in the context of the client thread which requested the creation of a logical channel.

The thread is in a critical section.

@param aChannel Set by this function to point to the created logical channel.

@return KErrNone if successful, otherwise one of the other system wide error codes.

*/

TInt DSoundScLddFactory::Create(DLogicalChannelBase*& aChannel)

	{

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLddFactory::Create"));

	aChannel=new DSoundScLdd;

	if (!aChannel)

		return(KErrNoMemory);

	return(KErrNone);

	}

/**

Check whether a channel has is currently open on the specified unit.

@param aUnit The number of the unit to be checked.

@return ETrue if a channel is open on the specified channel, EFalse otherwise.

@pre The unit info. mutex must be held.

*/

TBool DSoundScLddFactory::IsUnitOpen(TInt aUnit)

	{

	return(iUnitsOpenMask&(1<<aUnit));

	}

/**

Attempt to change the state of the channel open status for a particular channel.

@param aUnit The number of the unit to be updated.

@param aIsOpenSetting The required new state for the channel open status: either ETrue to set the status to open or 

	EFalse to set the status to closed.

@return KErrNone if the status was updated successfully, KErrInUse if an attempt has been made to set the channnel status

	to open while it is already open.

*/		

TInt DSoundScLddFactory::SetUnitOpen(TInt aUnit,TBool aIsOpenSetting)

	{

	NKern::FMWait(&iUnitInfoMutex); // Acquire the unit info. mutex.

	// Fail a request to open an channel that is already open

	if (aIsOpenSetting && IsUnitOpen(aUnit))

		{

		NKern::FMSignal(&iUnitInfoMutex); // Release the unit info. mutex.

		return(KErrInUse);

		}

	// Update the open status as requested

	if (aIsOpenSetting)

		iUnitsOpenMask|=(1<<aUnit);

	else

		iUnitsOpenMask&=~(1<<aUnit);

	NKern::FMSignal(&iUnitInfoMutex); // Release the unit info. mutex.	

	return(KErrNone);

	}	

/**

Constructor for the sound driver logical channel.

*/

DSoundScLdd::DSoundScLdd()

	: iPowerDownDfc(DSoundScLdd::PowerDownDfc,this,3),

	  iPowerUpDfc(DSoundScLdd::PowerUpDfc,this,3),

	  iEofTimer(DSoundScLdd::PlayEofTimerExpired,this),

	  iPlayEofDfc(DSoundScLdd::PlayEofTimerDfc,this,3)

	{

//	iDirection=ESoundDirRecord;

//	iState=EOpen;

// 	iBufConfig=NULL;

//	iPowerHandler=NULL;

//	iSoundConfigFlags=0;

//	iBytesTransferred=0;

//	iBufManager=NULL;

//	iTestSettings=0;

//	iPlayEofTimerActive=EFalse;

//	iThreadOpenCount=0;

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLdd::DSoundScLdd"));

	iUnit=-1;	// Invalid unit number

	// Many drivers would open the client thread's DThread object here. However, since this driver allows a channel to be shared by multiple client 

	// threads - we have to open and close the relevent DThread object for each request. 

	}

/**

Destructor for the sound driver logical channel.

*/

DSoundScLdd::~DSoundScLdd()

	{

	if (iNotifyChangeOfHwClientRequest)

		Kern::DestroyClientRequest(iNotifyChangeOfHwClientRequest);

	// Free the TClientRequest structures associated with requests

	if (iClientRequests)

		{

		for (TInt index=0; index<RSoundSc::ERequestRecordData+1; ++index)

			if (iClientRequests[index])

				Kern::DestroyClientRequest(iClientRequests[index]);

		delete[] iClientRequests;

		}

	// Check if we need to delete the shared chunk / audio buffers.

	if (iBufManager)

		delete iBufManager;

	// Delete any memory allocated to hold the current buffer configuration.

	if (iBufConfig)

		delete iBufConfig;

	// Remove and delete the power handler.

	if (iPowerHandler)

		{

		iPowerHandler->Remove(); 

		delete iPowerHandler;

		}

	// Delete the request queue

	if (iReqQueue)

		delete iReqQueue;		

	__ASSERT_DEBUG(iThreadOpenCount==0,Kern::Fault(KSoundLddPanic,__LINE__));	

	// Clear the 'units open mask' in the LDD factory.

	if (iUnit>=0)

		((DSoundScLddFactory*)iDevice)->SetUnitOpen(iUnit,EFalse);

	}

/**

Second stage constructor for the sound driver - called by the kernel's device driver framework.

This is called in the context of the client thread which requested the creation of a logical channel.

The thread is in a critical section.

@param aUnit The unit argument supplied by the client.

@param aInfo The info argument supplied by the client. Always NULL in this case.

@param aVer The version argument supplied by the client.

@return KErrNone if successful, otherwise one of the other system wide error codes.

*/

TInt DSoundScLdd::DoCreate(TInt aUnit, const TDesC8* /*aInfo*/, const TVersion& aVer)

	{

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLdd::DoCreate"));

	// Check the client has ECapabilityMultimediaDD capability.

	if (!Kern::CurrentThreadHasCapability(ECapabilityMultimediaDD,__PLATSEC_DIAGNOSTIC_STRING("Checked by ESOUNDSC.LDD (Sound driver)")))

		return(KErrPermissionDenied);

	// Check that the sound driver version specified by the client is compatible.

	if (!Kern::QueryVersionSupported(RSoundSc::VersionRequired(),aVer))

		return(KErrNotSupported);

	// Check that a channel hasn't already been opened on this unit.

	TInt r=((DSoundScLddFactory*)iDevice)->SetUnitOpen(aUnit,ETrue); // Try to update 'units open mask' in the LDD factory.

	if (r!=KErrNone)

		return(r);

	iUnit=aUnit;

	// Create a TClientRequest for each request that can be completed by the DFC thread.  These TClientRequest

	// instances are separate to those embedded in the TSoundScRequest structures and are used for requests that

	// have no associated TSoundScRequest structure or which are completing prematurely before they can be

	// associated with a TSoundScRequest structure

	if ((iClientRequests=new TClientRequest*[RSoundSc::ERequestRecordData+1])==NULL)

		return KErrNoMemory;

	for (TInt index=0; index<RSoundSc::ERequestRecordData+1; ++index)

		if ((r=Kern::CreateClientRequest(iClientRequests[index]))!=KErrNone)

			return r;

	if ((r=Kern::CreateClientDataRequest(iNotifyChangeOfHwClientRequest))!=KErrNone)

		return r;

	// Initialise the PDD

	Pdd()->iLdd=this;

	// Read back the capabilities of this device from the PDD and determine the data transfer direction for this unit.

	TPckg<TSoundFormatsSupportedV02> capsBuf(iCaps);

	Pdd()->Caps(capsBuf);

	iDirection=iCaps.iDirection;

	// Check the client has UserEnvironment capability if recording.

	if(iDirection==ESoundDirRecord)

		{

		if (!Kern::CurrentThreadHasCapability(ECapabilityUserEnvironment,__PLATSEC_DIAGNOSTIC_STRING("Checked by ESOUNDSC.LDD (Sound driver)")))

			return(KErrPermissionDenied);

		}

	// Create the appropriate request queue

	if (iDirection==ESoundDirPlayback)

		iReqQueue=new TSoundScPlayRequestQueue(this);

	else

		iReqQueue=new TSoundScRequestQueue(this);

	if (!iReqQueue)

		return(KErrNoMemory);

	r=iReqQueue->Create();

	if (r!=KErrNone)

		return(r);

	// Setup the default audio configuration acording to these capabilities.

	iSoundConfig.iChannels=HighestCapabilitySupported(iCaps.iChannels)+1;

	__ASSERT_ALWAYS(iSoundConfig.iChannels>0,Kern::Fault(KSoundLddPanic,__LINE__));

	iSoundConfig.iRate=(TSoundRate)HighestCapabilitySupported(iCaps.iRates);

	__ASSERT_ALWAYS(iSoundConfig.iRate>=0,Kern::Fault(KSoundLddPanic,__LINE__));

	iSoundConfig.iEncoding=(TSoundEncoding)HighestCapabilitySupported(iCaps.iEncodings);

	__ASSERT_ALWAYS(iSoundConfig.iEncoding>=0,Kern::Fault(KSoundLddPanic,__LINE__));

	iSoundConfig.iDataFormat=(TSoundDataFormat)HighestCapabilitySupported(iCaps.iDataFormats);

	__ASSERT_ALWAYS(iSoundConfig.iDataFormat>=0,Kern::Fault(KSoundLddPanic,__LINE__));

	__ASSERT_ALWAYS(ValidateConfig(iSoundConfig)==KErrNone,Kern::Fault(KSoundLddPanic,__LINE__));

	iSoundConfigFlags=0;

	// Setup the default setting for the record level / play volume.

	iVolume=KSoundMaxVolume;

	// Set up the correct DFC queue

	TDfcQue* dfcq=((DSoundScPdd*)iPdd)->DfcQ(aUnit);

	SetDfcQ(dfcq);

	iPowerDownDfc.SetDfcQ(dfcq);

	iPowerUpDfc.SetDfcQ(dfcq);

	iMsgQ.Receive();

	// Create the power handler

	iPowerHandler=new DSoundScPowerHandler(this);

	if (!iPowerHandler)

		return(KErrNoMemory);

	iPowerHandler->Add();

	// Power up the hardware.

	r=Pdd()->PowerUp();

	return(r);

	}

/**

Shutdown the audio device.

Terminate all device activity and power down the hardware.

*/

void DSoundScLdd::Shutdown()

	{

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLdd::Shutdown"));

	Pdd()->StopTransfer();

	// Power down the hardware

	Pdd()->PowerDown();

	// Cancel any requests that we may be handling	

	DoCancel(RSoundSc::EAllRequests);

	iState=EOpen;

	// Make sure DFCs and timers are not queued.

	iPowerDownDfc.Cancel();

	iPowerUpDfc.Cancel();

	CancelPlayEofTimer();

	}

/**

Process a request on this logical channel

Called in the context of the client thread.

@param aReqNo The request number:

  	          ==KMaxTInt: a 'DoCancel' message;

	          >=0: a 'DoControl' message with function number equal to value.

	          <0: a 'DoRequest' message with function number equal to ~value.

@param a1 The first request argument. For DoRequest(), this is a pointer to the TRequestStatus.

@param a2 The second request argument. For DoRequest(), this is a pointer to the 2 actual TAny* arguments.

@return The result of the request. This is ignored by device driver framework for DoRequest().

*/ 

TInt DSoundScLdd::Request(TInt aReqNo, TAny* a1, TAny* a2)

	{

//	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLdd::Request(%d)",aReqNo));

	TInt r;

	// Check for DoControl or DoRequest functions which are configured to execute in kernel thread context. This

	// also applies to DoCancel functions and ERequestRecordData requests where recording mode is not yet enabled.

	if ((aReqNo<RSoundSc::EMsgControlMax && aReqNo>(~RSoundSc::EMsgRequestMax)) ||

	    aReqNo==KMaxTInt ||

	    ((~aReqNo)==RSoundSc::ERequestRecordData && (iState==EOpen || iState==EConfigured)) 

	   )

		{

		// Implement in the context of the kernel thread - prepare and issue a kernel message.

		r=DLogicalChannel::Request(aReqNo,a1,a2);		

		}	

	else

		{

		// Implement in the context of the client thread.	

		// Decode the message type and dispatch it to the relevent handler function.

		if ((TUint)aReqNo<(TUint)KMaxTInt)

			r=DoControl(aReqNo,a1,a2,&Kern::CurrentThread());	// DoControl - process the request.

		else

			{

			// DoRequest - read the arguments from the client thread and process the request.

			TAny* a[2];

			kumemget32(a,a2,sizeof(a)); 

			TRequestStatus* status=(TRequestStatus*)a1;

			NKern::ThreadEnterCS(); 				// Need to be in critical section while manipulating the request/buffer list (for record).

			r=DoRequest(~aReqNo,status,a[0],a[1],&Kern::CurrentThread());

			// Complete request if there was an error

			if (r!=KErrNone)

				CompleteRequest(&Kern::CurrentThread(),status,r);

			r=KErrNone;

			NKern::ThreadLeaveCS();

			}

		}

//	__KTRACE_OPT(KSOUND1, Kern::Printf("<DSoundScLdd::Request - %d",r));

	return(r);

	}

/**

Send a message to the DFC thread for processing by HandleMsg().

This function is called in the context of the client thread.

Overridden to ensure client data is copied kernel-side to avoid page-faults.

@param aMsg  The message to process.

@return KErrNone if the message was send successfully, otherwise one of the other system-wide error

        codes.

*/

TInt DSoundScLdd::SendMsg(TMessageBase* aMsg)

	{

	// Executes in context of client thread

	TThreadMessage& m=*(TThreadMessage*)aMsg;

    TInt id = m.iValue;

	TInt r(KErrNone);

	if (id == ~RSoundSc::EMsgRequestPlayData)

		{

		r = PrePlay(aMsg);

		if (r!=KErrNone)

			{

			// This is an asynchronous request so need to return error through the TRequestStatus

			TRequestStatus* status = (TRequestStatus*)(m.Ptr0());

			Kern::RequestComplete(status,r);

			return(r);

			}

		r = DLogicalChannel::SendMsg(aMsg);

		if (r!=KErrNone)

			{

			iReqQueue->Free((TSoundScPlayRequest*)m.iArg[1]);	// Return the unused request object	

			}

		return(r);

		}

	else if (id == RSoundSc::EMsgControlSetBufChunkCreate || id == RSoundSc::EMsgControlSetBufChunkOpen)

		{

		r = PreSetBufferChunkCreateOrOpen(aMsg);

		if (r!=KErrNone)

			{

			return(r);

			}

		}

	else if (id == RSoundSc::EMsgControlSetAudioFormat)

		{

		r = PreSetSoundConfig(aMsg);

		if (r!=KErrNone)

			{

			return(r);

			}

		}

	r = DLogicalChannel::SendMsg(aMsg);

	return(r);

	}

/**

PreProcess a play request on this logical channel

Called in the context of the client thread.

@param aMsg  The message to process.

@return KErrNone if the parameters are validated and request structure populated. Otherwise a system-wide error.

*/ 

TInt DSoundScLdd::PrePlay(TMessageBase* aMsg)

	{

	__KTRACE_OPT(KSOUND1, Kern::Printf(">DSoundScLdd::PrePlay"));

	// Executes in context of client thread

	TThreadMessage* m=(TThreadMessage*)aMsg;

	// Copy play information to kernel side before checking

	SRequestPlayDataInfo info;

	kumemget(&info,m->iArg[1],sizeof(info));

	__KTRACE_OPT(KSOUND1, Kern::Printf("DSoundScLdd::PrePlay - off %x len %x flg %x ",info.iBufferOffset,info.iLength,info.iFlags));

	// validate parameters in the play structure

	// Check that the offset argument is aligned correctly for the PDD.

	TUint32 alignmask=(1<<iCaps.iRequestAlignment)-1; // iRequestAlignment holds log to base 2 of alignment required

	if ((info.iBufferOffset & alignmask) != 0)

		return(KErrArgument);

	// Check that the length argument is compatible with the minimum request size required for the PDD.

	if (iCaps.iRequestMinSize && info.iLength%iCaps.iRequestMinSize)

		return(KErrArgument);

	// Check that the specified offset and length are valid in the chunk. If so, get a pointer to the corresponding 

	// audio buffer object.

	TAudioBuffer* buf;

	if (iBufManager)

		{

		TInt r=iBufManager->ValidateRegion(info.iBufferOffset,info.iLength,buf);

		if (r!=KErrNone)

			return(r);

		}

	else

		{

		return(KErrNotReady);

		}	

	// Acquire a free request object and add it to the queue of pending requests.

	TSoundScPlayRequest* req=(TSoundScPlayRequest*)iReqQueue->NextFree();

	if (!req)

		return(KErrGeneral);										// Must have exceeded KMaxSndScRequestsPending.

	req->iTf.Init((TUint)buf,info.iBufferOffset,info.iLength,buf); 	// Use pointer to audio buffer as unique ID

	req->iFlags=info.iFlags;

	// replace the argument with a pointer to the kernel-side structure

	m->iArg[1]=req;

	__KTRACE_OPT(KSOUND1, Kern::Printf("<DSoundScLdd::PrePlay"));

	return(KErrNone);

	}