sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // e32/include/drivers/iic_channel.h
sl@0: // Include file for channel implementation
sl@0: //
sl@0: // WARNING: This file contains some APIs which are internal and are subject
sl@0: //          to change without notice. Such APIs should therefore not be used
sl@0: //          outside the Kernel and Hardware Services package.
sl@0: 
sl@0: /**
sl@0: @file
sl@0: @internalTechnology
sl@0: */
sl@0: #ifndef __IIC_CHANNEL_H__
sl@0: #define __IIC_CHANNEL_H__
sl@0: 
sl@0: #ifdef STANDALONE_CHANNEL
sl@0: #include <drivers/iic_transaction.h>
sl@0: #else
sl@0: #include <drivers/iic.h>
sl@0: #endif
sl@0: 
sl@0: static const char KIicChannelPanic[]="Iic Channel PIL";
sl@0: 
sl@0: const static TInt KChannelTypeMask	= 0x03;
sl@0: const static TInt KBusTypeShift		= 2;
sl@0: const static TInt KBusTypeMask		= 0x07<<KBusTypeShift; // number of buses may grow in future
sl@0: const static TInt KChannelDuplexShift= 5;
sl@0: const static TInt KChannelDuplexMask	= 0x01<<KChannelDuplexShift;
sl@0: const static TInt16 KTransCountMsBit = (TInt16)((TUint16)0x8000);
sl@0: 
sl@0: const static TInt8 KMaxWaitTime = 0x21; // Maximum allowable time in milliseconds for a Slave channel to wait for a response
sl@0: 										// (from Master or Client). This constant is used to limit run-time selected values
sl@0: 										// for timeouts. The value stated here is semi-arbitrary.
sl@0: 
sl@0: #ifdef IIC_SIMULATED_PSL
sl@0: // In a real system, the following timeout values are likely to be excessive. However, they are available
sl@0: // for use in the test framework, to account for the processing overhead.
sl@0: const TInt KSlaveDefMWaitTime = 32;
sl@0: const TInt KSlaveDefCWaitTime = 16;
sl@0: #else
sl@0: const TInt KSlaveDefMWaitTime = 1;	// Default wait time for Master timeout. PSL can use SetMasterWaitTime to override.
sl@0: const TInt KSlaveDefCWaitTime = 1;	// Default wait time for Client timeout. PSL can use SetClientWaitTime to override.
sl@0: #endif
sl@0: 
sl@0: 
sl@0: /**
sl@0: @internalComponent
sl@0: @prototype 9.6
sl@0: Base class for a Channel (not directly instantiable)
sl@0: */
sl@0: class DIicBusChannel : public DBase
sl@0: 	{
sl@0: public:
sl@0: 	enum TChannelType
sl@0: 		{
sl@0: 		EMaster			= 0,
sl@0: 		ESlave			= 0x01,
sl@0: 		EMasterSlave	= 0x02
sl@0: 		};
sl@0: 	enum TBusType
sl@0: 		{
sl@0: 		EI2c	   = 0,
sl@0: 		ESpi	   = 0x01,
sl@0: 		EMicrowire = 0x02,
sl@0: 		ECci	   = 0x03,
sl@0: 		ESccb	   = 0x04
sl@0: 		};
sl@0: 	enum TChannelDuplex
sl@0: 		{
sl@0: 		EHalfDuplex = 0,	// supports only half duplex transactions (even if bus spec supports full duplex)
sl@0: 		EFullDuplex = 0x1	// supports full duplex transactions (queud transactions may still be half duplex)
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 	virtual TInt StaticExtension(TUint aFunction, TAny* /*aParam1*/, TAny* /*aParam2*/)
sl@0: 		{
sl@0: #ifdef _DEBUG
sl@0: 		if(aFunction == KCtrlIoDumpChan)
sl@0: 			{
sl@0: 			DumpChannel();
sl@0: 			return KErrNone;
sl@0: 			}
sl@0: 		else
sl@0: #else
sl@0: 			(void)aFunction;
sl@0: #endif
sl@0: 
sl@0: 			return KErrNotSupported;
sl@0: 		};
sl@0: protected:
sl@0: 	// constructor
sl@0: 	inline DIicBusChannel(TChannelType aChanType, TBusType aBusType, TChannelDuplex aChanDuplex);
sl@0: 	// second phase construction - empty, to be implemented by derived types if required
sl@0: 	virtual TInt DoCreate()=0;
sl@0: 
sl@0: 	// helper function to read an set flags
sl@0: 	inline TChannelType ChannelType();
sl@0: 	inline void SetChannelType(TChannelType aChanType);
sl@0: 	inline TBusType BusType();
sl@0: 	inline void SetBusType(TBusType aBusType);
sl@0: 	inline TChannelDuplex ChannelDuplex();
sl@0: 	inline void SetChannelType(TChannelDuplex aChanDuplex);
sl@0: 	inline TInt8 ChannelNumber() const;
sl@0: 
sl@0: 	virtual TInt CheckHdr(TDes8* aHdr) = 0;	// PSL to check the header is valid for this channel
sl@0: protected:
sl@0: #ifdef _DEBUG
sl@0: 	inline void DumpChannel();
sl@0: #endif
sl@0: protected:
sl@0: 	NTimer iTimeoutTimer;	// timeout timer
sl@0: 	TInt8 iChannelNumber;	// this is the Key for ordering channels in the array
sl@0: 	TUint8 iFlags;			// combination of TChannelType, TChannelDuplex and TBusType
sl@0: 	TInt8 iSpare1;
sl@0: 	TInt8 iSpare2;
sl@0: private:
sl@0: 	TAny* iReserved;
sl@0: 
sl@0: 	friend class DIicBusController;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.6
sl@0: 
sl@0: Base class for a Master Channel (not directly instantiable)
sl@0: 
sl@0: */
sl@0: class DIicBusChannelMaster : public DIicBusChannel
sl@0: 	{
sl@0: public:
sl@0: 	// interface to Bus Controller (implemented by PIL)
sl@0: 	// For stand-alone channel, there is no controller. So some parts of
sl@0: 	// the interface are exported for client direct use. 
sl@0: 	/**
sl@0:     @publishedPartner
sl@0:     @prototype 9.6
sl@0:     Master channel interface to queue a transaction synchronously.
sl@0: 
sl@0:     @param aTransaction		A pointer to a transaction object containing the details of the transaction.
sl@0: 
sl@0:     @return KErrNone, when successfully completed;
sl@0: 			KErrArgument, if aTransaction is NULL;
sl@0: 			KErrTimedOut, if the channel terminates the transaction because  the addressed Slave exceeded the alloted time to respond;
sl@0:             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).
sl@0:     */
sl@0: 	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction);
sl@0:     /**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0:     Master channel interface to queue a transaction asynchronously.
sl@0: 
sl@0:     @param aTransaction		A pointer to a transaction object containing the details of the transaction.
sl@0:     @param aCallback		A pointer to a callback object.
sl@0: 
sl@0:     @return KErrNone, if successfully accepted; KErrArgument, if either aTransaction or aCallback are NULL;
sl@0:             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).
sl@0:     */
sl@0: 	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
sl@0:     /**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0:     Master channel interface to cancel a previously queued transaction.
sl@0: 
sl@0:     @param aTransaction		A pointer to a transaction object containing the details of the transaction.
sl@0: 
sl@0:     @return KErrCancel, if successfully cancelled; KErrArgument, if aTransaction is NULL;
sl@0: 			KErrNotFound if the transaction cannot be found on channel's queue of transactions;
sl@0: 			KErrInUse if this method is called on a transaction that has already been started;
sl@0:             KErrNotSupported, if the channel does not support Master mode, or the method is called on a synchronous transaction..
sl@0:     */
sl@0: 	virtual TInt CancelTransaction(TIicBusTransaction* aTransaction);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Master channel interface interface to provide extended functionality
sl@0: 
sl@0:     @param aFunction	A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;
sl@0: 						if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it
sl@0: 						extends the Slave channel interface.
sl@0:     @param aParam1		A generic argument to be passed to the function identified by aFunction.
sl@0:     @param aParam2		A generic argument to be passed to the function identified by aFunction.
sl@0: 
sl@0:     @return KErrNone, if successful;
sl@0: 			KErrNotSupported, function is not supported;
sl@0: 			Any other system wide error code.
sl@0: 	*/
sl@0: 	virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
sl@0: 
sl@0: //
sl@0: 	virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2);
sl@0: 
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Destructor for DIicBusChannelMaster
sl@0: 	*/
sl@0: 	~DIicBusChannelMaster();
sl@0: 
sl@0: protected:
sl@0: 	// PSL implemented
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Gateway function for PSL implementation (to be called by the interface APIs)
sl@0: 	*/
sl@0: 	virtual TInt DoRequest(TIicBusTransaction* aTransaction) = 0;
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function to be invoked in the event of a Slave timeout. May be overridden by the PSL.
sl@0: 	*/
sl@0: 	virtual TInt HandleSlaveTimeout() = 0;
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Second phase constructor to be implemented by the PSL
sl@0: 	*/
sl@0: 	virtual TInt DoCreate() = 0;
sl@0: 
sl@0: 	// Called by PSL
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Constructor for DIicBusChannelMaster
sl@0: 
sl@0: 	@param aBusType		Argument to specify the type of Bus
sl@0:     @param aChanDuplex	Argument to specify the duplex support offered by this channel
sl@0: 	*/
sl@0: 	DIicBusChannelMaster(TBusType aBusType, TChannelDuplex aChanDuplex);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function to instigate DIicBusChannel initialisation
sl@0: 
sl@0: 	@return KErrNone if no error
sl@0: 			KErrNoMemory if allocation of required objects
sl@0: 	*/
sl@0: 	TInt Init();
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to start the timer to check the Slave responsiveness.
sl@0: 
sl@0: 	@param aTime		Timeout in milliseconds
sl@0: 
sl@0: 	@return KErrNone if no error,
sl@0: 			KErrInUse if timer is already active.
sl@0: 
sl@0: 	*/
sl@0: 	TInt StartSlaveTimeOutTimer(TInt aTime);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to specify the DFC queue for the channel to use
sl@0: 
sl@0: 	@param aDfcQue		Pointer to the DFC queue to use
sl@0: 
sl@0: 	*/
sl@0: 	void SetDfcQ(TDfcQue* aDfcQue);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to Complete the transaction being processed by the channel
sl@0: 
sl@0: 	@param aResult		Error code to complete the transaction with
sl@0: 
sl@0: 	*/
sl@0: 	void CompleteRequest(TInt aResult);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to cancel the timer to check the Slave responsiveness.
sl@0: 
sl@0: 	*/
sl@0: 	void CancelTimeOut();
sl@0: 
sl@0: 	// Methods to make private data of TIicBusTransaction object accessible to derivatives of this class
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the Transaction Header of a specified TIicBusTransaction object
sl@0: 
sl@0: 	@return The Transaction Header of the specified TIicBusTransaction object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TDes8* GetTransactionHeader(const TIicBusTransaction* aTransaction);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the Half Duplex Transfer pointer of a specified TIicBusTransaction object
sl@0: 
sl@0: 	@return The Half Duplex Transfer pointer of the specified TIicBusTransaction object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TIicBusTransfer* GetTransHalfDuplexTferPtr(const TIicBusTransaction* aTransaction);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the Full Duplex Transfer pointer of a specified TIicBusTransaction object
sl@0: 
sl@0: 	@return The Full Duplex Transfer pointer of the specified TIicBusTransaction object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TIicBusTransfer* GetTransFullDuplexTferPtr(const TIicBusTransaction* aTransaction);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the address of the callback object of a specified TIicBusTransaction object
sl@0: 
sl@0: 	@return The address of the callback object of the specified TIicBusTransaction object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TIicBusCallback* GetTransCallback(const TIicBusTransaction* aTransaction);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the value of the TransFlags member of a specified TIicBusTransaction object
sl@0: 
sl@0: 	@return The value of the TransFlags member of the specified TIicBusTransaction object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TUint8 GetTransFlags(const TIicBusTransaction* aTransaction);
sl@0: 
sl@0: 	// Methods to make private data of TIicBusTransfer object accessible to derivatives of this class
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return Transfer Type the of a specified TIicBusTransfer object
sl@0: 
sl@0: 	@return The Transfer Type of the specified TIicBusTransfer object
sl@0: 
sl@0: 	@see TIicBusTransfer
sl@0: 	*/
sl@0: 	static inline TInt8 GetTferType(const TIicBusTransfer* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the Buffer Granularity of a specified TIicBusTransfer object
sl@0: 
sl@0: 	@return The Buffer Granularity of the specified TIicBusTransfer object
sl@0: 
sl@0: 	@see TIicBusTransfer
sl@0: 	*/
sl@0: 	static inline TInt8 GetTferBufGranularity(const TIicBusTransfer* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the descriptor for the data for a specified TIicBusTransfer object
sl@0: 
sl@0: 	@return The descriptor for the data for the specified TIicBusTransfer object
sl@0: 
sl@0: 	@see TIicBusTransfer
sl@0: 	*/
sl@0: 	static inline const TDes8* GetTferBuffer(const TIicBusTransfer* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the address of the next transfer for a specified TIicBusTransfer object
sl@0: 
sl@0: 	@return The address of the next transfer for the specified TIicBusTransfer object
sl@0: 
sl@0: 	@see TIicBusTransfer
sl@0: 	*/
sl@0: 	static inline TIicBusTransfer* GetTferNextTfer(const TIicBusTransfer* aTransfer);
sl@0: 
sl@0: 	// Methods to make private data of TIicBusTransactionPreamble object accessible to derivatives of this class
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function pointer for a specified TIicBusTransactionPreamble object
sl@0: 
sl@0: 	@return The function pointer for the specified TIicBusTransactionPreamble object
sl@0: 
sl@0: 	@see TIicBusTransactionPreamble
sl@0: 	*/
sl@0: 	static inline TIicBusPreamble GetPreambleFuncPtr(const TIicBusTransactionPreamble* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function argument for a specified TIicBusTransactionPreamble object
sl@0: 
sl@0: 	@return The function argument for the specified TIicBusTransactionPreamble object
sl@0: 
sl@0: 	@see TIicBusTransactionPreamble
sl@0: 	*/
sl@0: 	static inline TAny* GetPreambleFuncArg(const TIicBusTransactionPreamble* aTransfer);
sl@0: 
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function pointer of a specified TIicBusTransactionMultiTransc object
sl@0: 
sl@0: 	@return The function pointer of the specified TIicBusTransactionMultiTransc object
sl@0: 
sl@0: 	@see TIicBusTransactionMultiTransc
sl@0: 	*/
sl@0: 	static inline TIicBusMultiTranscCbFn GetMultiTranscFuncPtr(const TIicBusTransactionMultiTransc* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function argument of a specified TIicBusTransactionMultiTransc object
sl@0: 
sl@0: 	@return The function argument of the specified TIicBusTransactionMultiTransc object
sl@0: 
sl@0: 	@see TIicBusTransactionMultiTransc
sl@0: 	*/
sl@0: 	static inline TAny* GetMultiTranscFuncArg(const TIicBusTransactionMultiTransc* aTransfer);
sl@0: 
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function pointer of a specified TIicBusTransactionPreambleExt object
sl@0: 
sl@0: 	@return The function pointer of the specified TIicBusTransactionPreambleExt object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TIicBusMultiTranscCbFn GetExtTranscFuncPtr(const TIicBusTransactionPreambleExt* aTransfer);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Function to return the function argument of a specified TIicBusTransactionPreambleExt object
sl@0: 
sl@0: 	@return The function argument of the specified TIicBusTransactionPreambleExt object
sl@0: 
sl@0: 	@see TIicBusTransaction
sl@0: 	*/
sl@0: 	static inline TAny* GetExtTranscFuncArg(const TIicBusTransactionPreambleExt* aTransfer);
sl@0: 
sl@0: private:
sl@0: 	// Function to acquire the NFastMutex of the channel
sl@0: 	void Lock();
sl@0: 	// Function to release the NFastMutex of the channel
sl@0: 	void Unlock();
sl@0: 
sl@0: 	// function to run on receiving a message
sl@0:     static void MsgQFunc(TAny* aPtr);
sl@0: 
sl@0: 	TIicBusTransaction* NextTrans(TIicBusTransaction* aTrans);
sl@0: 	void EndTransaction(TIicBusTransaction* aTrans, TInt aResult, TIicBusCallback* aCb);
sl@0: 	void Complete(TInt aResult, TIicBusTransaction* aTransaction);
sl@0: 	void UnlockAndKick();
sl@0: 
sl@0: 	static void SlaveTimeoutCallback(TAny*);
sl@0: 
sl@0: 	// Used by DIidBusController (a friend of this class)
sl@0: 	TInt TransFlow(TIicBusTransaction* aTransaction);
sl@0: 
sl@0: 	TInt8 IsMasterBusy();
sl@0: 
sl@0: protected:
sl@0: 	TDfcQue* iDfcQ;
sl@0: 
sl@0: private:
sl@0: 	TDfc iTransQDfc;
sl@0: 	SOrdQue iTransactionQ;
sl@0: 	TIicBusTransaction* iTransaction;			// Pointer to current transaction
sl@0: 	TIicBusTransaction* iCurrentTransaction;	// Pointer to current fragment of a multiple transaction
sl@0: 
sl@0: 	NFastMutex iTransactionQLock;
sl@0: 
sl@0: 	TDfc* iSlaveTimeoutDfc;
sl@0: 
sl@0: 	TInt16 iTransCount; // Count of pending transactions
sl@0: 	TInt8 iChannelReady;
sl@0: 	TInt8 iSpare1;
sl@0: 
sl@0: private:
sl@0: 	TAny* iReserved1;
sl@0: 	TAny* iReserved2;
sl@0: 
sl@0: 	friend class DIicBusChannelMasterSlave;
sl@0: 	friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: @publishedPartner
sl@0: @prototype 9.6
sl@0: 
sl@0: Base class for a Slave Channel (not directly instantiable)
sl@0: 
sl@0: */
sl@0: class DIicBusChannelSlave : public DIicBusChannel
sl@0: 	{
sl@0: protected:
sl@0:     /**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	The set of operation values for processing by the PSL
sl@0:     */
sl@0: 	enum TPslOperation
sl@0: 		{
sl@0: 		ESyncConfigPwrUp = 0x01,
sl@0: 		EAsyncConfigPwrUp = 0x02,
sl@0: 		EPowerDown = 0x04,
sl@0: 		ETransmit = 0x08,
sl@0: 		EReceive = 0x10,
sl@0: 		EAbort = 0x20
sl@0: 		};
sl@0: private:
sl@0: 	// Values used by the internal state machine
sl@0: 	enum TSlaveTimerStates
sl@0: 		{
sl@0: 		EInactive = 0x01,
sl@0: 		EWaitForMaster = 0x02,
sl@0: 		EWaitForClient = 0x04,
sl@0: 		EClientTimeout = 0x08
sl@0: 		};
sl@0: 
sl@0: public:
sl@0: 
sl@0: 	// Interface to Controller.
sl@0:     // For stand-alone channel, the interface is exported.
sl@0:     /**
sl@0:     @publishedPartner
sl@0:     @prototype 9.6
sl@0:     Capture this Slave channel.
sl@0: 
sl@0:     @param aConfigHdr	A pointer to a descriptor containing the device specific configuration option applicable to all transactions.
sl@0:     @param aCallback	A pointer to a callback to be called upon specified triggers.
sl@0:     @param aChannelId	If this API is to complete synchronously, and the processing was successful, then on return aChannelId
sl@0:                       contains a platform-specific cookie that uniquely identifies the channel instance to be used by this client.
sl@0:                       If the processing was unsuccessful for the synchronous completion case, aChannelId will be unchanged.
sl@0:                       If the API was called to complete asynchronously, aChannelId will, in all cases, be set to zero; the valid
sl@0:                       value for the cookie will be set by the callback.
sl@0:     @param aAsynch		A boolean value that indicates if this API is to complete synchronously (EFalse) or asynchronously (ETrue).
sl@0: 
sl@0:     @return KErrNone, if successfully captured, or if API is asynchronous, if the request to capture the channel was accepted;
sl@0: 			KErrInUse if channel is already in use; KErrArgument, if aCallback is NULL;
sl@0:             KErrNotSupported, if the channel does not support Slave mode.
sl@0:     */
sl@0: 	virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0:     Release this previously captured Slave channel.
sl@0: 
sl@0:     @return KErrNone, if successfully released;
sl@0: 			KErrInUse if a transaction is currently underway on this channel; KErrArgument
sl@0:     */
sl@0: 	virtual TInt ReleaseChannel();
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Register a receive buffer with this Slave channel.
sl@0: 
sl@0:     @param aRxBuffer	A pointer to the receive buffer, in a client created descriptor.
sl@0: 	@param aBufGranularity The number of buffer bytes used to store a word.
sl@0:     @param aNumWords	The number of words expected to be received.
sl@0:     @param aOffset		The offset from the start of the buffer where to store the received data.
sl@0: 
sl@0:     @return KErrNone, if successfully registered;
sl@0: 			KErrAlreadyExists if a receive buffer is already pending;
sl@0: 			KErrArgument, if the pointer descriptor is NULL;
sl@0:     */
sl@0: 	virtual TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Register a transmit buffer with this Slave channel.
sl@0: 	This client may create a single buffer for the entire transaction and control where the received data
sl@0: 	is to be placed and the transmit data is to be found, by specifying the number of bytes to transmit (receive)
sl@0: 	and the offset into the buffer.
sl@0: 
sl@0:     @param aTxBuffer	A pointer to the transmit buffer, in a client created descriptor.
sl@0: 	@param aBufGranularity The number of buffer bytes used to store a word.
sl@0:     @param aNumWords	The number of words to be transmitted.
sl@0:     @param aOffset		The offset from the start of the buffer where to fetch the data to be transmitted.
sl@0: 
sl@0:     @return KErrNone, if successfully registered;
sl@0: 			KErrAlreadyExists if a transmit buffer is already pending;
sl@0: 			KErrArgument, if the pointer descriptor is NULL;
sl@0:     */
sl@0: 	virtual TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Sets the notification triggers and readies the receive path and/or kick starts a transmit (if the node is being addressed).
sl@0: 	It is only after a receive buffer has been registered and this API has been called that the channel is ready to receive data (when addressed).
sl@0: 	If a transmit buffer has been registered and this API has been called the channel will immediately transmit when addressed by the Master
sl@0: 	If the channel supports full duplex, both paths can be readied in one call to this API.
sl@0: 
sl@0:     @param aTrigger		A bitmask specifying the notification trigger. Masks for individual triggers are specified by the TIicBusSlaveTrigger enumeration.
sl@0: 
sl@0:     @return KErrNone, if successful;
sl@0: 			KErrArgument, if the trigger is invalid for this channel;
sl@0: 			KErrInUse if a transaction is already underway on this channel;
sl@0: 			KErrTimedOut, if the client exceeded the alloted time to respond by invoking this API;
sl@0:     */
sl@0: 	virtual TInt SetNotificationTrigger(TInt aTrigger);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Interface to provide extended functionality
sl@0: 
sl@0:     @param aFunction	A function identifier. If bit 31 is set and bit 30 cleared it is used to extend the Master-Slave channel;
sl@0: 						if bit 31 is cleared and bit 30 is set, it extends the Master channel; if both bits 31 and 30 are cleared it
sl@0: 						extends the Slave channel interface.
sl@0:     @param aParam1		A generic argument to be passed to the function identified by aFunction.
sl@0:     @param aParam2		A generic argument to be passed to the function identified by aFunction.
sl@0: 
sl@0:     @return KErrNone, if successful;
sl@0: 			KErrNotSupported, function is not supported;
sl@0: 			Any other system wide error code.
sl@0: 	*/
sl@0: 	virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
sl@0: //
sl@0: 	/**
sl@0: 	@internalTechnology
sl@0: 	@prototype 9.6
sl@0: 	Function reserved for future use
sl@0: 	*/
sl@0: 	virtual TInt Spare1(TInt aVal, TAny* aPtr1, TAny* aPtr2);
sl@0: 
sl@0: 	// Interface to TIicBusSlaveCallback
sl@0: 	// channel-specific function to process data received/transmitted (called from NotifyClient or DFC queued from it)
sl@0: 	// Must fill in the aCb object's iReturn, iRxWords and/or iTxWords using the appropriate funtions
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked when an asynchronous event occurs on the Slave channel. Implemented by the PSL.
sl@0:     @param aTrigger		Argument to indicate the type of event that occurred
sl@0:     @param aCb			Address of the Slave client callback object to process
sl@0: 
sl@0:     @return KErrNone, if successful;
sl@0: 			KErrNotSupported, function is not supported;
sl@0: 			Any other system wide error code.
sl@0: 	*/
sl@0: #ifdef STANDALONE_CHANNEL
sl@0: 	friend class TIicBusSlaveCallback;
sl@0: protected:
sl@0:     virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback*  aCb) = 0;
sl@0: private:
sl@0:     TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet);
sl@0:     void StartTimerByState();
sl@0:     void StopTimer();
sl@0: #else
sl@0: public:
sl@0:     virtual void ProcessData(TInt aTrigger, TIicBusSlaveCallback*  aCb) = 0;
sl@0:     virtual TInt UpdateReqTrig(TInt8& aCbTrigVal, TInt& aCallbackRet);
sl@0:     virtual void StartTimerByState();
sl@0:     virtual void StopTimer();
sl@0: #endif
sl@0: 
sl@0: public:
sl@0: 	// Values used by the Interface to TIicBusSlaveCallback
sl@0: 	enum TSlaveNotifProcSteps
sl@0: 		{
sl@0: 		EStopTimer = 0x01,
sl@0: 		EInvokeCb = 0x02,
sl@0: 		EStartTimer = 0x04
sl@0: 		};
sl@0: 
sl@0: protected:
sl@0: 	// PSL implemented
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	PSL specific second phase constructor
sl@0: 
sl@0: 	@return KErrNone, if succesful;
sl@0: 			KErrNotSupported, function is not supported;
sl@0: 			Any other system wide error code.
sl@0: 	*/
sl@0: 	virtual TInt DoCreate() = 0;
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Gateway function for PSL implementation: aOperation is a bitmask made of TPslOperation (to be called by the  interface APIs)
sl@0: 
sl@0: 	@return KErrNone, if succesful;
sl@0: 			KErrNotSupported, function is not supported;
sl@0: 			Any other system wide error code.
sl@0: 	*/
sl@0: 	virtual TInt DoRequest(TInt aOperation) = 0;
sl@0: 
sl@0: 	// Called by PSL
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 
sl@0: 	Constructor for DIicBusChannelSlave
sl@0: 
sl@0: 	@param aBusType		Argument to specify the type of Bus
sl@0:     @param aChanDuplex	Argument to specify the duplex support offered by this channel
sl@0: 	@param aChannelId	Argument to specify the identifier to use for this channel
sl@0: 	*/
sl@0: 	DIicBusChannelSlave(TBusType aBusType, TChannelDuplex aChanDuplex, TInt16 aChannelId);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function to instigate DIicBusChannelSlave initialisation
sl@0: 
sl@0: 	@return KErrNone
sl@0: 	*/
sl@0: 	TInt Init();
sl@0: 	
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Destructor for DIicBusChannelSlave
sl@0: 	*/
sl@0: 	~DIicBusChannelSlave();
sl@0: 
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked when an asynchronous channel capture completes
sl@0: 
sl@0: 	@param aResult		Argument specifying the error code reurned by the capture operation
sl@0: 
sl@0: 	@return KErrNone
sl@0: 	*/
sl@0: 	void ChanCaptureCallback(TInt aResult);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked to instigate processing by the PSL, PIL and Client when an asynchronous event occurs
sl@0: 
sl@0: 	@param aResult		Argument specifying the trigger value associated with the asynchronous event
sl@0: 
sl@0: 	@return KErrNone
sl@0: 	*/
sl@0: 	void NotifyClient(TInt aTrigger);
sl@0: 
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked by the PSL to set the timeout period to wait for a response from the bus master
sl@0: 
sl@0: 	@param aWaitTime		Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime)
sl@0: 
sl@0: 	@return KErrNone, if succesful;
sl@0: 	KErrArgument, if aWaitTime > KMaxWaitTime
sl@0: 	*/
sl@0: 	TInt SetMasterWaitTime(TInt8 aWaitTime);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked by the PSL to get the timeout period to wait for a response from the bus master
sl@0: 
sl@0: 	@return The wait time, in milliseconds
sl@0: 	*/
sl@0: 	inline TInt8 GetMasterWaitTime();
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked by the PSL to set the timeout period to wait for a response from the Client
sl@0: 
sl@0: 	@param aWaitTime		Argument specifying the wait time, in milliseconds (limit=KMaxWaitTime)
sl@0: 	@return KErrNone
sl@0: 	*/
sl@0: 	TInt SetClientWaitTime(TInt8 aWaitTime);
sl@0: 	/**
sl@0: 	@publishedPartner
sl@0: 	@prototype 9.6
sl@0: 	Function invoked by the PSL to get the timeout period to wait for a response from the Client
sl@0: 
sl@0: 	@return The wait time, in milliseconds
sl@0: 	*/
sl@0: 	inline TInt8 GetClientWaitTime();
sl@0: private:
sl@0: 	//Method to instruct PSL to indicate a bus error to the bus Master, then return
sl@0: 	void SendBusErrorAndReturn();
sl@0: 	void SetChannelId(TInt& aChannelId);
sl@0: 
sl@0: 	void CompleteAsynchCapture(TInt aResult);
sl@0: 	void SlaveTimerCallBack();
sl@0: 	static void SlaveStaticCB(TAny* aDumPtr);
sl@0: 
sl@0: protected:
sl@0: 	TInt8 iRxGranularity;
sl@0: 	TInt8 iTxGranularity;
sl@0: 	TInt8 iNumRxWords;
sl@0: 	TInt8 iNumTxWords;
sl@0: 	TInt8 iRxOffset;
sl@0: 	TInt8 iTxOffset;
sl@0: private:
sl@0: 	TInt8 iChannelInUse;
sl@0: 	TInt8 iSpare1;
sl@0: protected:
sl@0: 	TInt16 iChannelId;		// channel identifier to be returned to client (in aChannelId)
sl@0: private:
sl@0: 	TInt16 iInstanceCount;	// instance count part of aChannelId
sl@0: protected:
sl@0: 	TDes8* iConfigHeader;
sl@0: 	TInt8* iTxBuf;
sl@0: 	TInt8* iRxBuf;
sl@0: private:
sl@0: 	TIicBusSlaveCallback* iNotif;
sl@0: 	TDfc* iClientTimeoutDfc;	// To be queued on the dfc queue used by iNotif
sl@0: 	DThread* iClient;		// stored when client captures channel
sl@0: #ifndef STANDALONE_CHANNEL
sl@0: 	DIicBusController* iController;
sl@0: #endif
sl@0: 
sl@0: 	TInt8 iTimerState;
sl@0: 	TInt8 iMasterWaitTime;	// 8 bits allows maximum wait time of 0.25 seconds
sl@0: 	TInt8 iClientWaitTime;	// 8 bits allows maximum wait time of 0.25 seconds
sl@0: 	TInt8 iSpare2;
sl@0: 
sl@0: 	TInt8 iReqTrig;			// Represents the trigger required by the Client (bitmask from TIicBusSlaveTrigger).
sl@0: 	TInt8 iAccumTrig;		// Represents the events accumulated during the current trigger period
sl@0: 	TInt16 iSpare3;
sl@0: 
sl@0: 	TSpinLock iSpinLock;
sl@0: 	TAny* iReserved1;
sl@0: 	TAny* iReserved2;
sl@0: 
sl@0: 	friend class DIicBusChannelMasterSlave;
sl@0: 	friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: @internalComponent
sl@0: @prototype 9.6
sl@0: The Master-Slave Channel class (not for derivation)
sl@0: */
sl@0: class DIicBusChannelMasterSlave : public DIicBusChannel
sl@0: 	{
sl@0: public:
sl@0: 	// constructor
sl@0: #ifdef STANDALONE_CHANNEL
sl@0:     IMPORT_C DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan);    
sl@0: #else
sl@0: 	inline DIicBusChannelMasterSlave(TBusType aBusType, TChannelDuplex aChanDuplex, DIicBusChannelMaster* aMasterChan, DIicBusChannelSlave* aSlaveChan);
sl@0: #endif
sl@0: 	~DIicBusChannelMasterSlave(){delete iMasterChannel; delete iSlaveChannel; }
sl@0: 	inline TInt DoCreate();
sl@0: 	// Master side interface to Bus Controller
sl@0: 	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction);
sl@0: 	virtual TInt QueueTransaction(TIicBusTransaction* aTransaction, TIicBusCallback* aCallback);
sl@0: 	inline TInt CancelTransaction(TIicBusTransaction* aTransaction);
sl@0: 
sl@0: 	// Slave side interface to Bus Controller
sl@0: 	virtual TInt CaptureChannel(TDes8* aConfigHdr, TIicBusSlaveCallback* aCallback, TInt& aChannelId, TBool aAsynch);
sl@0: 	virtual TInt ReleaseChannel();  
sl@0: 	inline TInt RegisterRxBuffer(TPtr8 aRxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
sl@0: 	inline TInt RegisterTxBuffer(TPtr8 aTxBuffer, TInt8 aBufGranularity, TInt8 aNumWords, TInt8 aOffset);
sl@0: 	inline TInt SetNotificationTrigger(TInt aTrigger);
sl@0: 	virtual TInt StaticExtension(TUint aFunction, TAny* aParam1, TAny* aParam2);
sl@0: 
sl@0: private:
sl@0: 	// Base class support
sl@0: 	virtual TInt CheckHdr(TDes8* /*aHdr*/){	__ASSERT_DEBUG(0,Kern::Fault("DIicBusChannelMasterSlave::CheckHdr",__LINE__));	\
sl@0: 											return KErrGeneral;}; // Not accessed. PSL implementation for Master or Slave used.
sl@0: protected:
sl@0: 	DIicBusChannelMaster* iMasterChannel;
sl@0: 	DIicBusChannelSlave* iSlaveChannel;
sl@0: private:
sl@0: 
sl@0: 	friend class DIicBusChannelMaster;
sl@0: 	friend class DIicBusChannelSlave;
sl@0: 	friend class DIicBusController; // For static method DIicBusController::DeRegisterChannel
sl@0: 	};
sl@0: 
sl@0: #include <drivers/iic_channel.inl>
sl@0: 
sl@0: #endif  // #ifndef __IIC_CHANNEL_H__
sl@0: