// Copyright (c) 2008-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/include/drivers/iic_channel.h

// Include file for channel implementation

//

// WARNING: This file contains some APIs which are internal and are subject

//          to change without notice. Such APIs should therefore not be used

//          outside the Kernel and Hardware Services package.

/**

@file

@internalTechnology

*/

#ifndef __IIC_CHANNEL_H__

#define __IIC_CHANNEL_H__

#ifdef STANDALONE_CHANNEL

#include <drivers/iic_transaction.h>

#else

#include <drivers/iic.h>

#endif

static const char KIicChannelPanic[]="Iic Channel PIL";

const static TInt KChannelTypeMask	= 0x03;

const static TInt KBusTypeShift		= 2;

const static TInt KBusTypeMask		= 0x07<<KBusTypeShift; // number of buses may grow in future

const static TInt KChannelDuplexShift= 5;

const static TInt KChannelDuplexMask	= 0x01<<KChannelDuplexShift;

const static TInt16 KTransCountMsBit = (TInt16)((TUint16)0x8000);

const static TInt8 KMaxWaitTime = 0x21; // Maximum allowable time in milliseconds for a Slave channel to wait for a response

										// (from Master or Client). This constant is used to limit run-time selected values

										// for timeouts. The value stated here is semi-arbitrary.

#ifdef IIC_SIMULATED_PSL

// In a real system, the following timeout values are likely to be excessive. However, they are available

// for use in the test framework, to account for the processing overhead.

const TInt KSlaveDefMWaitTime = 32;

const TInt KSlaveDefCWaitTime = 16;

#else

const TInt KSlaveDefMWaitTime = 1;	// Default wait time for Master timeout. PSL can use SetMasterWaitTime to override.

const TInt KSlaveDefCWaitTime = 1;	// Default wait time for Client timeout. PSL can use SetClientWaitTime to override.

#endif

/**

@internalComponent

@prototype 9.6

Base class for a Channel (not directly instantiable)

*/

class DIicBusChannel : public DBase

	{

public:

	enum TChannelType

		{

		EMaster			= 0,

		ESlave			= 0x01,

		EMasterSlave	= 0x02

		};

	enum TBusType

		{

		EI2c	   = 0,

		ESpi	   = 0x01,

		EMicrowire = 0x02,

		ECci	   = 0x03,

		ESccb	   = 0x04

		};

	enum TChannelDuplex

		{

		EHalfDuplex = 0,	// supports only half duplex transactions (even if bus spec supports full duplex)

		EFullDuplex = 0x1	// supports full duplex transactions (queud transactions may still be half duplex)

		};

public:

	virtual TInt StaticExtension(TUint aFunction, TAny* /*aParam1*/, TAny* /*aParam2*/)

		{

#ifdef _DEBUG

		if(aFunction == KCtrlIoDumpChan)

			{

			DumpChannel();

			return KErrNone;

			}

		else

#else

			(void)aFunction;

#endif

			return KErrNotSupported;

		};

protected:

	// constructor

	inline DIicBusChannel(TChannelType aChanType, TBusType aBusType, TChannelDuplex aChanDuplex);

	// second phase construction - empty, to be implemented by derived types if required

	virtual TInt DoCreate()=0;

	// helper function to read an set flags

	inline TChannelType ChannelType();

	inline void SetChannelType(TChannelType aChanType);

	inline TBusType BusType();

	inline void SetBusType(TBusType aBusType);

	inline TChannelDuplex ChannelDuplex();

	inline void SetChannelType(TChannelDuplex aChanDuplex);

	inline TInt8 ChannelNumber() const;

	virtual TInt CheckHdr(TDes8* aHdr) = 0;	// PSL to check the header is valid for this channel

protected:

#ifdef _DEBUG

	inline void DumpChannel();

#endif

protected:

	NTimer iTimeoutTimer;	// timeout timer

	TInt8 iChannelNumber;	// this is the Key for ordering channels in the array

	TUint8 iFlags;			// combination of TChannelType, TChannelDuplex and TBusType

	TInt8 iSpare1;

	TInt8 iSpare2;

private:

	TAny* iReserved;

	friend class DIicBusController;

	};

/**

@publishedPartner

@prototype 9.6

Base class for a Master Channel (not directly instantiable)

*/

class DIicBusChannelMaster : public DIicBusChannel

	{

public:

	// interface to Bus Controller (implemented by PIL)

	// For stand-alone channel, there is no controller. So some parts of

	// the interface are exported for client direct use. 

	/**

    @publishedPartner

    @prototype 9.6

    Master channel interface to queue a transaction synchronously.

    @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    @return KErrNone, when successfully completed;

			KErrArgument, if aTransaction is NULL;

			KErrTimedOut, if the channel terminates the transaction because  the addressed Slave exceeded the alloted time to respond;

            KErrNotSupported, if either the channel does not support Master mode or the transaction is not valid on this channel (e.g. valid full duplex transaction queued on half duplex channel).

    */

	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction);

    /**

	@publishedPartner

	@prototype 9.6

    Master channel interface to queue a transaction asynchronously.

    @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    @param aCallback		A pointer to a callback object.

    @return KErrNone, if successfully accepted; KErrArgument, if either aTransaction or aCallback are NULL;

            KErrNotSupported, if either the channel does not support Master mode or the transaction is not valid on this channel(e.g. valid full duplex transaction queued on half duplex channel).

    */

	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);

    /**

	@publishedPartner

	@prototype 9.6

    Master channel interface to cancel a previously queued transaction.

    @param aTransaction		A pointer to a transaction object containing the details of the transaction.

    @return KErrCancel, if successfully cancelled; KErrArgument, if aTransaction is NULL;

			KErrNotFound if the transaction cannot be found on channel's queue of transactions;

			KErrInUse if this method is called on a transaction that has already been started;

            KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction..

    */

	virtual TInt CancelTransaction(TIicBusTransaction* aTransaction);

	/**

	@publishedPartner

	@prototype 9.6

	Master channel interface interface to provide extended functionality

    @param aFunction	A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;

						if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it

						extends the Slave channel interface.

    @param aParam1		A generic argument to be passed to the function identified by aFunction.

    @param aParam2		A generic argument to be passed to the function identified by aFunction.

    @return KErrNone, if successful;

			KErrNotSupported, function is not supported;

			Any other system wide error code.

	*/

	virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);

//

	virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2);

	/**

	@publishedPartner

	@prototype 9.6

	Destructor for DIicBusChannelMaster

	*/

	~DIicBusChannelMaster();

protected:

	// PSL implemented

	/**

	@publishedPartner

	@prototype 9.6

	Gateway function for PSL implementation (to be called by the interface APIs)

	*/

	virtual TInt DoRequest(TIicBusTransaction* aTransaction) = 0;

	/**

	@publishedPartner

	@prototype 9.6

	Function to be invoked in the event of a Slave timeout. May be overridden by the PSL.

	*/

	virtual TInt HandleSlaveTimeout() = 0;

	/**

	@publishedPartner

	@prototype 9.6

	Second phase constructor to be implemented by the PSL

	*/

	virtual TInt DoCreate() = 0;

	// Called by PSL

	/**

	@publishedPartner

	@prototype 9.6

	Constructor for DIicBusChannelMaster

	@param aBusType		Argument to specify the type of Bus

    @param aChanDuplex	Argument to specify the duplex support offered by this channel

	*/

	DIicBusChannelMaster(TBusType aBusType, TChannelDuplex aChanDuplex);

	/**

	@publishedPartner

	@prototype 9.6

	Function to instigate DIicBusChannel initialisation

	@return KErrNone if no error

			KErrNoMemory if allocation of required objects

	*/

	TInt Init();

	/**

	@publishedPartner

	@prototype 9.6

	Function to start the timer to check the Slave responsiveness.

	@param aTime		Timeout in milliseconds

	@return KErrNone if no error,

			KErrInUse if timer is already active.

	*/

	TInt StartSlaveTimeOutTimer(TInt aTime);

	/**

	@publishedPartner

	@prototype 9.6

	Function to specify the DFC queue for the channel to use

	@param aDfcQue		Pointer to the DFC queue to use

	*/

	void SetDfcQ(TDfcQue* aDfcQue);

	/**

	@publishedPartner

	@prototype 9.6

	Function to Complete the transaction being processed by the channel

	@param aResult		Error code to complete the transaction with

	*/

	void CompleteRequest(TInt aResult);

	/**

	@publishedPartner

	@prototype 9.6

	Function to cancel the timer to check the Slave responsiveness.

	*/

	void CancelTimeOut();

	// Methods to make private data of TIicBusTransaction object accessible to derivatives of this class

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the Transaction Header of a specified TIicBusTransaction object

	@return The Transaction Header of the specified TIicBusTransaction object

	@see TIicBusTransaction

	*/

	static inline TDes8* GetTransactionHeader(const TIicBusTransaction* aTransaction);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the Half Duplex Transfer pointer of a specified TIicBusTransaction object

	@return The Half Duplex Transfer pointer of the specified TIicBusTransaction object

	@see TIicBusTransaction

	*/

	static inline TIicBusTransfer* GetTransHalfDuplexTferPtr(const TIicBusTransaction* aTransaction);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the Full Duplex Transfer pointer of a specified TIicBusTransaction object

	@return The Full Duplex Transfer pointer of the specified TIicBusTransaction object

	@see TIicBusTransaction

	*/

	static inline TIicBusTransfer* GetTransFullDuplexTferPtr(const TIicBusTransaction* aTransaction);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the address of the callback object of a specified TIicBusTransaction object

	@return The address of the callback object of the specified TIicBusTransaction object

	@see TIicBusTransaction

	*/

	static inline TIicBusCallback* GetTransCallback(const TIicBusTransaction* aTransaction);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the value of the TransFlags member of a specified TIicBusTransaction object

	@return The value of the TransFlags member of the specified TIicBusTransaction object

	@see TIicBusTransaction

	*/

	static inline TUint8 GetTransFlags(const TIicBusTransaction* aTransaction);

	// Methods to make private data of TIicBusTransfer object accessible to derivatives of this class

	/**

	@publishedPartner

	@prototype 9.6

	Function to return Transfer Type the of a specified TIicBusTransfer object

	@return The Transfer Type of the specified TIicBusTransfer object

	@see TIicBusTransfer

	*/

	static inline TInt8 GetTferType(const TIicBusTransfer* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the Buffer Granularity of a specified TIicBusTransfer object

	@return The Buffer Granularity of the specified TIicBusTransfer object

	@see TIicBusTransfer

	*/

	static inline TInt8 GetTferBufGranularity(const TIicBusTransfer* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the descriptor for the data for a specified TIicBusTransfer object

	@return The descriptor for the data for the specified TIicBusTransfer object

	@see TIicBusTransfer

	*/

	static inline const TDes8* GetTferBuffer(const TIicBusTransfer* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the address of the next transfer for a specified TIicBusTransfer object

	@return The address of the next transfer for the specified TIicBusTransfer object

	@see TIicBusTransfer

	*/

	static inline TIicBusTransfer* GetTferNextTfer(const TIicBusTransfer* aTransfer);

	// Methods to make private data of TIicBusTransactionPreamble object accessible to derivatives of this class

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function pointer for a specified TIicBusTransactionPreamble object

	@return The function pointer for the specified TIicBusTransactionPreamble object

	@see TIicBusTransactionPreamble

	*/

	static inline TIicBusPreamble GetPreambleFuncPtr(const TIicBusTransactionPreamble* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function argument for a specified TIicBusTransactionPreamble object

	@return The function argument for the specified TIicBusTransactionPreamble object

	@see TIicBusTransactionPreamble

	*/

	static inline TAny* GetPreambleFuncArg(const TIicBusTransactionPreamble* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function pointer of a specified TIicBusTransactionMultiTransc object

	@return The function pointer of the specified TIicBusTransactionMultiTransc object

	@see TIicBusTransactionMultiTransc

	*/

	static inline TIicBusMultiTranscCbFn GetMultiTranscFuncPtr(const TIicBusTransactionMultiTransc* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function argument of a specified TIicBusTransactionMultiTransc object

	@return The function argument of the specified TIicBusTransactionMultiTransc object

	@see TIicBusTransactionMultiTransc

	*/

	static inline TAny* GetMultiTranscFuncArg(const TIicBusTransactionMultiTransc* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function pointer of a specified TIicBusTransactionPreambleExt object

	@return The function pointer of the specified TIicBusTransactionPreambleExt object

	@see TIicBusTransaction

	*/

	static inline TIicBusMultiTranscCbFn GetExtTranscFuncPtr(const TIicBusTransactionPreambleExt* aTransfer);

	/**

	@publishedPartner

	@prototype 9.6

	Function to return the function argument of a specified TIicBusTransactionPreambleExt object

	@return The function argument of the specified TIicBusTransactionPreambleExt object

	@see TIicBusTransaction

	*/

	static inline TAny* GetExtTranscFuncArg(const TIicBusTransactionPreambleExt* aTransfer);

private:

	// Function to acquire the NFastMutex of the channel

	void Lock();

	// Function to release the NFastMutex of the channel

	void Unlock();

	// function to run on receiving a message

    static void MsgQFunc(TAny* aPtr);

	TIicBusTransaction* NextTrans(TIicBusTransaction* aTrans);

	void EndTransaction(TIicBusTransaction* aTrans, TInt aResult, TIicBusCallback* aCb);

	void Complete(TInt aResult, TIicBusTransaction* aTransaction);

	void UnlockAndKick();

	static void SlaveTimeoutCallback(TAny*);

	// Used by DIidBusController (a friend of this class)

	TInt TransFlow(TIicBusTransaction* aTransaction);

	TInt8 IsMasterBusy();

protected:

	TDfcQue* iDfcQ;

private:

	TDfc iTransQDfc;

	SOrdQue iTransactionQ;

	TIicBusTransaction* iTransaction;			// Pointer to current transaction

	TIicBusTransaction* iCurrentTransaction;	// Pointer to current fragment of a multiple transaction

	NFastMutex iTransactionQLock;

	TDfc* iSlaveTimeoutDfc;

	TInt16 iTransCount; // Count of pending transactions

	TInt8 iChannelReady;

	TInt8 iSpare1;

private:

	TAny* iReserved1;

	TAny* iReserved2;

	friend class DIicBusChannelMasterSlave;

	friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel

	};

/**

@publishedPartner

@prototype 9.6

Base class for a Slave Channel (not directly instantiable)

*/

class DIicBusChannelSlave : public DIicBusChannel

	{

protected:

    /**

	@publishedPartner

	@prototype 9.6

	The set of operation values for processing by the PSL