/*

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

*

*/

#include <drivers/iic.h>

#include <drivers/iic_channel.h>

// #include <gpio.h>	// Include if using GPIO functionality

#include "iic_psl.h"

#include "iic_slave.h"

// The timeout period to wait for a response from the client, expressed in milliseconds

// This is converted to timer ticks by the PIL, so the maximum value is 2147483.

// The value should be selected to allow for the longest, slowest transfer

// const TInt KClientWaitTime = 2; // 2mS, when debugging might set up to KMaxWaitTime

// In an SMP system, use a spin lock to guard access to member variables iTrigger and iInProgress

#ifdef __SMP__

static TSpinLock IicPslSpinLock = TSpinLock(TSpinLock::EOrderGenericIrqLow3);

#endif

// Callback function for the iHwGuardTimer timer. 

//

// Called in ISR context if the iHwGuardTimer expires. Sets iTransactionStatus to KErrTimedOut

//

void DIicBusChannelSlavePsl::TimeoutCallback(TAny* aPtr)

	{

	__KTRACE_OPT(KIIC, Kern::Printf("DCsiChannelMaster::TimeoutCallback"));

	DIicBusChannelSlavePsl *a = (DIicBusChannelSlavePsl*) aPtr;

	a->iTransactionStatus = KErrTimedOut;

	}

// Static method called by the ISR when the Master has ended a transfer

//

// The method checks and reports the Rx and Tx status to the PIL by calling NotifyClient with a bitmask described as follows:.

// - If a Tx transfer has ended before all the data was transmitted, bitmask = (ETxAllBytes | ETxOverrun)

// - If a Tx transfer has ended and all the data was transmitted, bitmask = ETxAllBytes

// - If a Rx transfer has ended before the expected amount of data was received, bitmask = (ERxAllBytes | ERxUnderrun)

// - If a Rx transfer has ended and the expected amount of data was received, bitmask = ERxAllBytes

//

void DIicBusChannelSlavePsl::NotifyClientEnd(DIicBusChannelSlavePsl* aPtr)

	{

	__KTRACE_OPT(KIIC, Kern::Printf("NotifyClientEnd, iTrigger %x", aPtr->iTrigger));

	// Since a transfer has ended, may wish to disable interrupts at this point

	// This will likely be supported with calls similar to the following:

	//		AsspRegister::Write32(aPtr->iChannelBase + KBusInterruptEnableOffset, KIicPslBusDisableBitMask);

	//		Interrupt::Disable(aPtr->iRxInterruptId);

	//		Interrupt::Disable(aPtr->iTxInterruptId);

	// iTrigger will have bits ETransmit and EReceive set according to the operation requested in the call to DoRequest

	// Use variable flag for the bitmask to pass into the PIL method NotifyClient

	TInt flag = 0;

	if(aPtr->iTrigger & EReceive)

		{

		// Requested Rx operation has ended - check for RxUnderrun

		flag = ERxAllBytes;

		if(aPtr->iRxDataEnd != aPtr->iRxData)

			{

			flag |= ERxUnderrun;

			}

		}

	if(aPtr->iTrigger & ETransmit)

		{

		// Requested Tx operation has ended - check for RxOverrun

		flag |= ETxAllBytes;

		if(aPtr->iTxDataEnd != aPtr->iTxData)

			{

			flag |= ETxOverrun;

			}

		}

	aPtr->NotifyClient(flag);

	}

// ISR Handler

//

// The ISR handler identifies the cause of the interrupt that lead to its invocation:

// if the cause was transfer-related, it calls the PIL function NotifyClient to report a summary of the transfer status;

// if the cause was completion of asynchronous channel capture, PIL function ChanCaptureCallback is called 

//

// The ISR also clears the source of the interrupt, and (for transfer-related interrupts) transfers the next data 

// between buffers and the hardware and updates the member variable iInProgress to indicate if a transfer has started or

// ended. If a transfer has ended before the expected amount of data has been transfered it calls function NotifyClientEnd.

//

void DIicBusChannelSlavePsl::IicPslIsr(TAny* /*aPtr*/)

	{

	//		DIicBusChannelSlavePsl *a = (DIicBusChannelSlavePsl*) aPtr;

	//		TInt intState = 0;	// Variable to support use of spin lock

	//		TInt trigger = 0; // Record the Rx and Tx transfers

	//		TUint32 intStatus = 0; // Record of the interrupts that are being reported

	// Identify the cause of the interrupt. If this can be achieved by reading a single register,

	// code similar to the following could be used:

	//		intStatus = AsspRegister::Read32(a->iChannelBase + KIntStatusOffset);

	// Optional (not required if asynchronous channel capture is not supported)

	// If the cause of the interrupt is completion of asynchronous channel capture, the ISR will check the appropriate

	// indicator for confirmation of success - for a real PSL, this may be by querying a bitmask in a register. For the template PSL,

	// however, a dummy member variable (iAsyncConfig) has been used to represent the asynchronous operation instead.

	//

	//		if(iAsyncConfig == 1)	// Replace with a check of the indicator that the interrupt was due to asynchrous channel capture

	//			{

	//			// The PIL function ChanCaptureCallback is now to be invoked. It takes as an argument either KErrNone or a

	//			// system-wide error code to indicate the cause of failure. For a real PSL, the argument would likely be determined

	//			// by reading a bitmask in a status register - but for the template port, just use KErrNone.

	//			//

	//			a->ChanCaptureCallback(KErrNone);

	//			return;

	//			}

	// If an interrupt indicates that a transfer has started, or that it has now ended, (such as a chip select 

	// line transition for a SPI bus the member variable iInProgress should be modified accordingly. This should

	// be done under the guard of spin lock macros since iInProgress can be accessed in the context of the Client

	// thread (in DoRequest, ProcessData and InitTransfer). The following structure should be adopted:

	//		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

	//		<access a->iInProgress>

	//		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

	//

	// If a transfer has ended before the expected amount of data has been transfered, function NotifyClientEnd

	// should be called, as follows:

	//		a->NotifyClientEnd(a);

	//		return;	// Return now - the interrupt indicated transfer end, not receipt or transmission of data.

	// The transfers that had been started are indicated by the bitmask held in member variable iTrigger.

	// This must be accessed under the guard of a spin lock since it can be accessed in the context of the

	// Client thread (in DoRequest, ProcessData and InitTransfer). The following structure should be adopted:

	//		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

	//		trigger = a->iTrigger;

	//		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

	// If the interrupt was raised for a Tx event, and a Tx transfer had been started (so the interrupt was not spurious)

	// then either prepare the next data to send, or, if all the data has been sent, call the PIL function NotifyClient

	// with bitmask (ETxAllBytes | ETxUnderrun) so that, if the Client specified a ETxUnderrun notification, it will be alerted

	// and can determine whether another buffer of data should be provide for transmission.

	// Code similar to the following could be used:

	//		if(intStatus & KTxInterruptBitMask)

	//			{

	//			if(trigger & ETransmit)

	//				{

	//				// Interrupt was not spurious

	//				if(a->iTxData == a->iTxDataEnd)

	//					{

	//					// All the data to be transmitted has been sent, so call the PIL method NotifyClient

	//					a->NotifyClient(ETxAllBytes | ETxUnderrun);

	//					}

	//				else

	//					{

	//					// There is more data to be sent

	//					// TUint8 nextTxValue = *iTxData;	// For this example, assumes one byte of data is to be transmitted

	//														// but if operating in 16-bit mode, bytes may need arranging for

	//														// endianness

	//

	//					// Write to the Tx register with something similar to the following:

	//					//		AsspRegister::Write32(iChannelBase + KTxFifoOffset, nextTxValue);

	//

	//					iTxData += iWordSize;	// Then increment the pointer to the data. In this example, 8-bit mode is assumed

	//											// (iWordSize=1), but if operating in 16-bit mode iTxData would be incremented

	//											// by the number of bytes specified in iWordSize

	//					}

	//				}

	//			}

	// If the interrupt was raised for a Rx event, and a Rx transfer had been started (so the interrupt was not spurious)

	// read the received data from the hardware to the buffer. If a Rx FIFO is being used, use a loop to drain it - until

	// the FIFO is empty or the buffer is full. If data remains after the buffer is full, an RxOverrun condition has occurred

	// - so the PIL function NotifyClient should be called with bitmask (ERxAllBytes | ERxOverrun) so that, if the Client specified

	// a ERxOverrun notification, it will be alerted and can determine whether another buffer should be provided to continue reception.

	// Code similar to the following could be used:

	//		if(intStatus & KRxInterruptBitMask)

	//			{

	//			if(trigger & EReceive)

	//				{

	//				// Interrupt was not spurious

	//				while(AsspRegister::Read32(a->iChannelBase + KRxFifoLevelOffset))

	//					{

	//					if((a->iRxData - a->iRxDataEnd) >= a->iWordSize)

	//						{

	//						// Space remains in the buffer, so copy the received data to it

	//						TUint8 nextRxValue = AsspRegister::Read32(a->iChannelBase + KRxFifoOffset);

	//						*a->iRxData = nextRxValue;	// For this example, assumes one byte of data is to be transmitted

	//													// but if operating in 16-bit mode, bytes may need arranging for

	//													// endianness

	//

	//						a->iRxData += a->iWordSize;	// Then increment the pointer to the data. In this example, 8-bit mode is assumed

	//													// (iWordSize=1), but if operating in 16-bit mode iRxData would be incremented

	//													// by the number of bytes specified in iWordSize

	//						}

	//					else

	//						{

	//						// The buffer is full but more data has been received - so there is an RxOverrun condition

	//						// Disable the hardware from receiving any more data and call the PIL function NotifyClient

	//						// with bitmask (ERxAllBytes | ERxOverrun).

	//						AsspRegister::Write32(a->iChannelBase + KRxFifoControl, KRxFifoDisableBitMask);

	//						a->NotifyClient(ERxAllBytes | ERxOverrun);

	//						break;

	//						}

	//					}

	//				}

	//			else

	//				{

	//				// If the interrupt was spurious, ignore the data, and reset the FIFO

	//				AsspRegister::Write32(a->iChannelBase + KRxFifoControl, KRxFifoClearBitMask);

	//				}

	// Once the interrupts have been processed, clear the source. If this can be achieve by writing to

	// a single register, code similar to the following could be used:

	//		AsspRegister::Write32(a->iChannelBase + KIntStatusOffset, KAIntBitMask);

	}

// Constructor, first stage

//

// The PSL is responsible for setting the channel number - this is passed as the first parameter to

// this overload of the base class constructor

//

DIicBusChannelSlavePsl::DIicBusChannelSlavePsl(TInt aChannelNumber, TBusType aBusType, TChannelDuplex aChanDuplex) :

	DIicBusChannelSlave(aBusType, aChanDuplex, 0),	// Base class constructor. Initalise channel ID to zero.

	iHwGuardTimer(TimeoutCallback, this)			// Timer to guard against hardware timeout

	{

	iChannelNumber = aChannelNumber;

	__KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::DIicBusChannelSlavePsl, iChannelNumber = %d\n", iChannelNumber));

	}

// Second stage construction

//

// Allocate and initialise objects required by the PSL channel implementation

//

TInt DIicBusChannelSlavePsl::DoCreate()

	{

	__KTRACE_OPT(KIIC, Kern::Printf("\nDIicBusChannelSlavePsl::DoCreate, ch: %d \n", iChannelNumber));

	TInt r = KErrNone;

	// PIL Base class initialization.

	r = Init();

	if(r == KErrNone)

		{

		// At a minimum, this function must set the channel's unique channel ID.

		// When the channel is captured, this value will be combined with an instance count

		// provided by the PIL to generate a value that will be used by a client as a unique

		// identifer in subsequent calls to the Slave API.

		//

		// There is no set format for the ID, it just needs to be unique.

		// Un-comment and complete the following line:

//		iChannelId = 

		// This method may also be concerned with setting the base register address iChannelBase), and allocating

		// any objects that will be required to support operaton until the channel is deleted.

		//

		// Un-comment and complete the following line:

//		iChannelBase = 

		}

	return r;

	}

// static method used to construct the DIicBusChannelSlavePsl object.

DIicBusChannelSlavePsl* DIicBusChannelSlavePsl::New(TInt aChannelNumber, const TBusType aBusType, const TChannelDuplex aChanDuplex)

	{

	__KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::NewL(): aChannelNumber = %d, BusType =%d", aChannelNumber, aBusType));

	DIicBusChannelSlavePsl *pChan = new DIicBusChannelSlavePsl(aChannelNumber, aBusType, aChanDuplex);

	TInt r = KErrNoMemory;

	if (pChan)

		{

		r = pChan->DoCreate();

		}

	if (r != KErrNone)

		{

		delete pChan;

		pChan = NULL;

		}

	return pChan;

	}

// Validates the configuration information specified by the client when capturing the channel

//

// Called by the PIL as part of the Slave CaptureChannel processing

//

// If the pointer to the header is NULL, return KErrArgument.

// If the content of the header is not valid for this channel, return KErrNotSupported.

// 

TInt DIicBusChannelSlavePsl::CheckHdr(TDes8* aHdrBuff)

	{

	TInt r = KErrNone;

	if(!aHdrBuff)

		{

		r = KErrArgument;

		}

	else

		{

		// Check that the contents of the header are valid

		//

		// The header will be specific to a particular bus type. Using a fictional

		// bus type Abc,code similar to the following could be used to validate each

		// member of the header:

		// 

		//		TConfigAbcBufV01* headerBuf = (TConfigAbcBufV01*) aHdrBuff;

		//		TConfigAbcV01 &abcHeader = (*headerBuf)();

		//		if(	(abcHeader.iHeaderMember < ESomeMinValue)	||

		//			(abcHeader.iHeaderMember > ESomeMaxValue))

		//			{

		//			__KTRACE_OPT(KIIC, Kern::Printf("iHeaderMember %d not supported",abcHeader.iHeaderMember));

		//			r = KErrNotSupported;

		//			}

		}

	__KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::CheckHdr() r %d", r));

	return r;

	}

// Method called in the context of the client thread, as a consequence of the PSL invocation of the 

// PIL method NotifyClient when a bus event occurs.

//

// This method updates the bitmask of requested operations (held in member variable iTrigger) and the

// PIL counts of data received and transmitted. If the event was a bus error, the bitmask of requested operations

// is cleared.

//

void DIicBusChannelSlavePsl::ProcessData(TInt aTrigger, TIicBusSlaveCallback* aCb)

	{

	__KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::ProcessData(), trigger: %x\n", aTrigger));

	TInt intState;

	// If using the iInProgress member variable to indicate transitions on a chip-select line, and an interrupt

	// occurred as a transfer was to end, then must ensure the transmission of data has ceased.

	//

	// Must use spin lock to guard access since iInProgress is accessed by the ISR

	//

	TInt inProgress;

	intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

	inProgress = iInProgress;

	__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

	//

	if(!inProgress &&								// Transfer has now ended

	   (aTrigger & (ERxAllBytes | ETxAllBytes)))	// Master has not yet finished transferring data

		{

		// Use the guard timer to make sure that transfer ends with an expected time - if this does not cease 

		// before the timer expires, iTransactionStatus will be set to KErrTimedOut by the callback function TimeoutCallback

		//

		// Poll the relevant register to check for transfer activity, using code similar to the following:

		//		TInt8 transferring = AsspRegister::Read32(iChannelBase + KStatusRegisterOffset) & KTransferringBitMask);

		// For the template port, use a dummy variable instead of the register access (transferring = 1)

		//

		TInt8 transferring = 1;

		iTransactionStatus = KErrNone;

		iHwGuardTimer.OneShot(NKern::TimerTicks(KTimeoutValue));

		while((iTransactionStatus == KErrNone) &&

		      transferring);		// Replace transferring with a register read, as described above

		// At this point, either the transfer has ceased, or the timer expired - in either case, may disable the interrupt

		// for the transfer now, using code similar to the following:

		//		AsspRegister::Write32(iChannelBase + KIntEnableRegisterOffset, KIntDisableBitMask);

		// Check for guard timer expiry

		if(iTransactionStatus != KErrNone)

			{

			__KTRACE_OPT(KIIC, Kern::Printf("DIicBusChannelSlavePsl::ProcessData - Transaction timed-out"));

			return;

			}

		else

			{

			iHwGuardTimer.Cancel();

			}

		// If all transfer activity has now ceased, clear iTrigger

		// Must use spin lock to guard access since iInProgress is accessed by the ISR

		//

		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

		iTrigger = 0;

		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

		}

	// If the PSL called the PIL function NotifyClient to indicate transfer activity (or error), the reason

	// will be specified as a bitmask in aTrigger

	//  - if a Rx event occurred, the ERxAllBytes flag will be set

	//  - if a Tx event occurred, the ETxAllBytes flag will be set

	//  - if a bus error occurred, the EGeneralBusError flag will be set

	//

	if(aTrigger & ERxAllBytes)

		{

		__KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Rx Buf:    %x\n", iRxData));

		__KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Rx Bufend: %x\n", iRxDataEnd));

		// Clear the internal EReceive flag

		// This must be done under guard of a spin lock since iTrigger is accessed by the ISR

		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

		iTrigger &= ~EReceive;

		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

		// Update the PIL count of Rx data (in the Callback object)

		aCb->SetRxWords(iNumRxWords - ((iRxDataEnd - iRxData) / iWordSize));

		}

	// 

	if(aTrigger & ETxAllBytes)

		{

		__KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Tx Buf:    %x\n", iTxData));

		__KTRACE_OPT(KIIC, Kern::Printf("ProcessData - Tx Bufend: %x\n", iTxDataEnd));

		// Clear the internal ETransmit flag..

		// This must be done under guard of a spin lock since iTrigger is accessed by the ISR

		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

		iTrigger &= ~ETransmit;

		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

		// Update the PIL count of Tx data (in the Callback object)

		aCb->SetTxWords(iNumTxWords - ((iTxDataEnd - iTxData) / iWordSize));

		}

	//

	if(aTrigger & EGeneralBusError)

		{

		__KTRACE_OPT(KIIC, Kern::Printf("BusError.."));

		// Clear and disable relevant interrupts, possibly using code similar to the following:

		//		AsspRegister::Write32(iChannelBase + KIntEnableRegisterOffset, KIntDisableBitMask);

		// Clear internal flags

		// This must be done under guard of a spin lock since iTrigger is accessed by the ISR

		intState = __SPIN_LOCK_IRQSAVE(IicPslSpinLock);

		iTrigger = 0;

		__SPIN_UNLOCK_IRQRESTORE(IicPslSpinLock, intState);

		}

	// Set the callback's trigger, for use by the PIL

	aCb->SetTrigger(aTrigger | aCb->GetTrigger());

	}

// Method to initialise the hardware in accordance with the data provided by the Client

// in the configuration header when capturing the channel

//

// This method is called from DoRequest and is expected to return a value to indicate success

// or a system wide error code to inform of the failure

//

TInt DIicBusChannelSlavePsl::ConfigureInterface()

	{

	__KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface()"));

	TInt r = KErrNone;

	// The header is stored in member variable iConfigHeader, and will be specific to a particular bus type.

	// Using a fictional bus type Abc, code similar to the following could be used to access each

	// member of the header:

	// 

	//		TConfigAbcBufV01* headerBuf = (TConfigAbcBufV01*) iConfigHeader;

	//		TConfigAbcV01 &abcHeader = (*headerBuf)();

	//		TInt value = abcHeader.iTintMember;

	// Initialising the hardware may be achieved with calls similar to the following:

	//		AsspRegister::Write32(a->iChannelBase + KBusModeControlOffset, KIicPslModeControlBitMask);

	//		GPIO::SetPinMode(aPinId, GPIO::EEnabled);

	// Binding an ISR may be achieved with calls similar to the following:

	//		r = Interrupt::Bind(iRxInterruptId, DIicBusChannelSlavePsl::IicPslIsr, this);

	//		r = Interrupt::Bind(iTxInterruptId, DIicBusChannelSlavePsl::IicPslIsr, this);

	// Enabling interrupts may be achieved with calls similar to the following:

	//		r = Interrupt::Enable(iRxInterruptId);

	//		r = Interrupt::Enable(iTxInterruptId);

	// Modifying a hardware register may not be a zero-delay operation. The member variable iHwGuardTimer could be used to guard a

	// continuous poll of the hardware register that checks for the required change in the setting; TimeoutCallback is already 

	// assigned as the callback function for iHwGaurdTimer, and it modifies member variable iTransactionStatus to indicate a timeout

	// - so the two could be used together as follows:

	//		iTransactionStatus = KErrNone;

	//		iHwGuardTimer.OneShot(NKern::TimerTicks(KTimeoutValue));

	//		while((iTransactionStatus == KErrNone) &&

	//		       AsspRegister::Read32(iChannelBase + KRegisterOffset) & KRegisterFlagBitMask);

	//		if(iTransactionStatus != KErrNone)

	//			{

	//			r = KErrGeneral;

	//			}

	//		else

	//			{

	//			iHwGuardTimer.Cancel();

	//			}

	// DoRequest checks the return value so the variable r should be modified in the event of failure with a system-wide error code

	// for example, if a register could not be modified,

	//			r = KErrGeneral;

	//			__KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface failed with error %d\n",r));

	return r;

	}

// Method to start asynchronous initialisation of the hardware, in accordance with the data provided by the Client

// in the configuration header when capturing the channel. This differs from ConfigureInterface in that it

// merely starts the initialisation, then returns immediately; 

//

// The PSL is expected to be implemented as an asynchronous state machine, where events (for example hardware 

// interrupts, or timer expiry) invoke callback functions that advance the state machine to the next state. Once

// all the required states have been transitioned, so that the PSL part of the CaptureChannel processing is 

// complete, the ISR should be invoked, which will then call PIL method ChanCaptureCallback

//

// This method is called from DoRequest and is expected to return a value to indicate success

// or a system wide error code to inform of the failure

//

TInt DIicBusChannelSlavePsl::AsynchConfigureInterface()

	{

	__KTRACE_OPT(KIIC, Kern::Printf("ConfigureInterface()"));

//	TInt r = KErrNone;	// A real implementation would use this as the return value to indicate success / failure