/*

* 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_transaction.h

*

*/

// 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_TRANSACTION_H__

#define __IIC_TRANSACTION_H__

#include <kernel/kern_priv.h> // for DThread;

#include <e32ver.h>

static const char KIicPanic[]="Iic PIL";

const TInt KNumTrancPriorities=8;

const TUint8 KTransactionWithPreamble = 0x80;

const TUint8 KTransactionWithMultiTransc = 0x40;

#ifdef _DEBUG

static const TUint KCtrlIoDumpChan = 1;	// StaticExtension value reserved for printing a channel

#endif

/**

@publishedPartner

@prototype 9.6

The set of endianness values for use with IIC buses

*/

enum TEndianness

	{

	EBigEndian,

	ELittleEndian

	};

/**

@publishedPartner

@prototype 9.6

The set of bit-order values for use with IIC buses

*/

enum TBitOrder

	{

	ELsbFirst,

	EMsbFirst

	};

//

// Bus-specific configuration for SPI bus

//

/**

@publishedPartner

@prototype 9.6

The set of word-width values for use with TConfigSpiV01

@see TConfigSpiV01

*/

enum TSpiWordWidth

	{

	ESpiWordWidth_8,

	ESpiWordWidth_10,

	ESpiWordWidth_12,

	ESpiWordWidth_16

	};

/**

@publishedPartner

@prototype 9.6

The set of clock mode values for use with TConfigSpiV01

@see TConfigSpiV01

*/

enum TSpiClkMode

	{

	ESpiPolarityLowRisingEdge,		// Active high, odd edges

	ESpiPolarityLowFallingEdge,		// Active high, even edges

	ESpiPolarityHighFallingEdge,	// Active low,  odd edges

	ESpiPolarityHighRisingEdge		// Active low,  even edges

	};

/**

@publishedPartner

@prototype 9.6

The set of values to represent the pin sense when selecting a Slave

@see TConfigSpiV01

*/

enum TSpiSsPinMode

    {

    ESpiCSPinActiveLow,      // Active low

    ESpiCSPinActiveHigh     // Active high

    };

/**

@publishedPartner

@prototype 9.6

Class to represent the configuration data for a SPI bus channel registered with IIC

*/

class TConfigSpiV01

	{

public:

	TSpiWordWidth iWordWidth;

	TInt32        iClkSpeedHz;

	TSpiClkMode   iClkMode;

	TInt32        iTimeoutPeriod;

	TEndianness   iEndianness;

	TBitOrder     iBitOrder;

	TUint         iTransactionWaitCycles;

	TSpiSsPinMode iSSPinActiveMode;

	};

typedef TPckgBuf <TConfigSpiV01> TConfigSpiBufV01;

//

// Bus-specific configuration for I2C bus

//

/**

@publishedPartner

@prototype 9.6

The set of address types for use with TConfigI2cV01

@see TConfigI2cV01

*/

enum TI2cAddrType

	{

	EI2cAddr7Bit,

	EI2cAddr10Bit

	};

/**

@publishedPartner

@prototype 9.6

Class to represent the configuration data for a I2C bus channel registered with IIC

*/

class TConfigI2cV01

	{

	public:

	TI2cAddrType	iAddrType;		// 7 or 10-bit addressing

	TInt32			iClkSpeedHz;

	TEndianness		iEndianness;

	TInt32			iTimeoutPeriod;

	};

typedef TPckgBuf <TConfigI2cV01> TConfigI2cBufV01;

// Bus realisation configuration

//

// 31 30 29 28 | 27 26 25 24 | 23 22 21 20 | 19 18 17 16 | 15 14 13 12 | 11 10  9  8 |  7  6  5  4 |  3  2  1  0

//

// 31:29 - HS Master address (I2C only)

// 28    - HS address valid bit

// 27:23 - Reserved

// 22:20 - Bus type

// 19:15 - Channel number

// 14:10 - Transaction speed

//  9:0  - Slave address

#define HS_MASTER_ADDR_SHIFT 29

#define HS_MASTER_ADDR_MASK 0x7

#define HS_ADDR_VALID_SHIFT 28

#define HS_ADDR_VALID_MASK 0x1

#define BUS_TYPE_SHIFT 20

#define BUS_TYPE_MASK 0x7

#define CHANNEL_NO_SHIFT 15

#define CHANNEL_NO_MASK 0x1F

#define TRANS_SPEED_SHIFT 10

#define TRANS_SPEED_MASK 0x1F

#define SLAVE_ADDR_SHIFT 0

#define SLAVE_ADDR_MASK 0x3FF

// The SET_CONF_FIELD and GET_CONF_FIELD are for internal use, only.

// They are to support the set of macros below which access particular fields of the Bus realisation configuration

#define SET_CONF_FIELD(aBusId,aField,aMask,aShift) aBusId=(aBusId&~(aMask<<aShift))|((aField&aMask)<<aShift);

#define GET_CONF_FIELD(aBusId,aMask,aShift) (((aBusId)>>(aShift))&(aMask))

/**

@publishedPartner

@prototype 9.6

Macro to get the HS Master address of a Bus realisation configuration

*/

#define GET_HS_MASTER_ADDR(aBusId) GET_CONF_FIELD(aBusId,HS_MASTER_ADDR_MASK,HS_MASTER_ADDR_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the HS Master address of a Bus realisation configuration

*/

#define SET_HS_MASTER_ADDR(aBusId,aHsMasterAddr) SET_CONF_FIELD(aBusId,aHsMasterAddr,HS_MASTER_ADDR_MASK,HS_MASTER_ADDR_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to get the HS address valid bit of a Bus realisation configuration

*/

#define GET_HS_VALID(aBusId,aHsValid) GET_CONF_FIELD(aBusId,aHsValid,HS_ADDR_VALID_MASK,HS_ADDR_VALID_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the HS address valid bit of a Bus realisation configuration

*/

#define SET_HS_VALID(aBusId,aHsValid) SET_CONF_FIELD(aBusId,aHsValid,HS_ADDR_VALID_MASK,HS_ADDR_VALID_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to get the Bus type of a Bus realisation configuration

*/

#define GET_BUS_TYPE(aBusId) GET_CONF_FIELD(aBusId,BUS_TYPE_MASK,BUS_TYPE_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the Bus type of a Bus realisation configuration

*/

#define SET_BUS_TYPE(aBusId,aBusType) SET_CONF_FIELD(aBusId,aBusType,BUS_TYPE_MASK,BUS_TYPE_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to get the Channel number of a Bus realisation configuration

*/

#define GET_CHAN_NUM(aBusId) GET_CONF_FIELD(aBusId,CHANNEL_NO_MASK,CHANNEL_NO_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the Channel number of a Bus realisation configuration

*/

#define SET_CHAN_NUM(aBusId,aChanNum) SET_CONF_FIELD(aBusId,aChanNum,CHANNEL_NO_MASK,CHANNEL_NO_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the Transaction speed of a Bus realisation configuration

*/

#define SET_TRANS_SPEED(aBusId,aTransSpeed) SET_CONF_FIELD(aBusId,aTransSpeed,TRANS_SPEED_MASK,TRANS_SPEED_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to get the Transaction speed of a Bus realisation configuration

*/

#define GET_TRANS_SPEED(aBusId) GET_CONF_FIELD(aBusId,TRANS_SPEED_MASK,TRANS_SPEED_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to set the Slave address of a Bus realisation configuration

*/

#define SET_SLAVE_ADDR(aBusId,aSlaveAddr) SET_CONF_FIELD(aBusId,aSlaveAddr,SLAVE_ADDR_MASK,SLAVE_ADDR_SHIFT)

/**

@publishedPartner

@prototype 9.6

Macro to get the Slave address of a Bus realisation configuration

*/

#define GET_SLAVE_ADDR(aBusId) GET_CONF_FIELD(aBusId,SLAVE_ADDR_MASK,SLAVE_ADDR_SHIFT)

// The SET_CONFIG_FIELD and GET_CONFIG_FIELD are for internal use, only.

// They are to support the TIicBusRealisation class

// These macros should be considered deprecated - they will be removed when the TIicBusRealisation class is removed

#define SET_CONFIG_FIELD(aField,aMask,aShift) iConfig=(iConfig&~(aMask<<aShift))|((aField&aMask)<<aShift)

#define GET_CONFIG_FIELD(aField,aMask,aShift) aField=((iConfig>>aShift)&aMask)

/**

@publishedPartner

@deprecated

Class to represent and provide access to configuration data used on a per-transaction basis with IIC

*/

class TIicBusRealisationConfig

	{

public:

	// default constructor - just resets the value..

	inline TIicBusRealisationConfig() : iConfig(0) {}

	inline TIicBusRealisationConfig& operator=(const TIicBusRealisationConfig &aObj){iConfig = aObj.GetConfig(); return *this;}

	inline void Clear() {iConfig = 0;}

	inline TUint32 GetConfig() const {return iConfig;}

	inline void SetConfig(TUint32 aConfig) {iConfig = aConfig;}

	inline void SetHsMasterAddr(TUint8 aHsMasterAddr) {SET_CONFIG_FIELD(aHsMasterAddr,HS_MASTER_ADDR_MASK,HS_MASTER_ADDR_SHIFT);};

	inline void GetHsMasterAddr(TUint8& aHsMasterAddr) const {{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,HS_MASTER_ADDR_MASK,HS_MASTER_ADDR_SHIFT);aHsMasterAddr=(TUint8)tempVar;};};

	inline void SetHsValid(TUint8 aHsValid) {SET_CONFIG_FIELD(aHsValid,HS_ADDR_VALID_MASK,HS_ADDR_VALID_SHIFT);};

	inline void GetHsValid(TUint8& aHsValid) const{{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,HS_ADDR_VALID_MASK,HS_ADDR_VALID_SHIFT);aHsValid=(TUint8)tempVar;};};

	inline void SetBusType(TUint8 aBusType) {SET_CONFIG_FIELD(aBusType,BUS_TYPE_MASK,BUS_TYPE_SHIFT);};

	inline void GetBusType(TUint8& aBusType) const {{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,BUS_TYPE_MASK,BUS_TYPE_SHIFT);aBusType=(TUint8)tempVar;};};

	inline void SetChanNum(TUint8 aChanNum) {SET_CONFIG_FIELD(aChanNum,CHANNEL_NO_MASK,CHANNEL_NO_SHIFT);};

	inline void GetChanNum(TUint8& aChanNum) const {{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,CHANNEL_NO_MASK,CHANNEL_NO_SHIFT);aChanNum=(TUint8)tempVar;};};

	inline void SetTransSpeed(TUint8 aTransSpeed) {SET_CONFIG_FIELD(aTransSpeed,TRANS_SPEED_MASK,TRANS_SPEED_SHIFT);};

	inline void GetTransSpeed(TUint8& aTransSpeed) const {{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,TRANS_SPEED_MASK,TRANS_SPEED_SHIFT);aTransSpeed=(TUint8)tempVar;};};

	inline void SetSlaveAddr(TUint16 aSlaveAddr) {SET_CONFIG_FIELD(aSlaveAddr,SLAVE_ADDR_MASK,SLAVE_ADDR_SHIFT);};

	inline void GetSlaveAddr(TUint16& aSlaveAddr) const {{TUint32 tempVar;GET_CONFIG_FIELD(tempVar,SLAVE_ADDR_MASK,SLAVE_ADDR_SHIFT);aSlaveAddr=(TUint16)tempVar;};};

private:

	TUint32 iConfig;

	};

// Forward declarations

class TIicBusTransaction;

class DIicBusChannelMaster;

//

// Master-side items

//

/**

@publishedPartner

@prototype 9.6

Class to represent and provide access to configuration data used on a per-transaction basis with IIC

@see TIicBusTransaction

*/

class TIicBusTransfer

	{

public:

	enum TReqType

		{

		EMasterRead,

		EMasterWrite,

		};

	// the client interface for creating and linking simple requests

	// default constructor..

	inline TIicBusTransfer();

	inline TIicBusTransfer(TReqType aType, TInt8 aGranularity, TDes8* aBuffer);

	inline void LinkAfter(TIicBusTransfer* aPrev);

	inline TInt8 WordWidth();

	inline TReqType Direction();

	inline TInt Length();

	inline const TIicBusTransfer* Next();

	inline TInt SetTransferData(TReqType aType, TInt8 aGranularity, TDes8* aBuffer);

    const TDes8* GetBuffer() {return (const TDes8*)iBuffer;}

private:

	TInt8 iType;			// as one of TReqType

	TInt8 iBufGranularity;	// width of a transfer word in bits

	TInt8 iSpare1;

	TDes8* iBuffer;	// the data for this transfer (packed into 8-bit words with padding). Access must be guarded for safety.

	TIicBusTransfer* iNext;

	TIicBusTransaction* iTransaction;	// pointer to the TIicBusTransaction owning the list that this transfer has been added to

	friend class TIicBusTransaction;

	friend class DIicBusChannelMaster;

	};

const TInt8 KTransferQueued = 0x01;

/**

@publishedPartner

@prototype 9.6

Definition of function prototype for a callback function provided by a client

for invocation on the after the client transaction has been processed by a Master

channel. The function will be executed in the context of the client thread.

@see TIicBusTransaction

*/

typedef void (*TIicBusCbFn)(TIicBusTransaction* /*aTransction*/,

	                  TInt  /*aBusId*/,

	                  TInt  /*aResult*/,

	                  TAny* /*aParam*/);

class TIicBusCallback; // Forward declaration

/**

@publishedPartner

@prototype 9.6

Class to represent a transaction for processing by an IIC Master Channel

@see IicBus

*/

class TIicBusTransaction : public SOrdQueLink

	{

    public:

        enum TState {EFree,EDelivered,EAccepted};

        //default constuctor.

        inline TIicBusTransaction();

        // the client interface for creating half duplex transactions

        inline TIicBusTransaction(TDes8* aHeader, TIicBusTransfer* aHdTrans, TInt aPriority=0);

        inline ~TIicBusTransaction();

        inline TInt SetHalfDuplexTrans(TDes8* aHeader, TIicBusTransfer* aHdTrans);

        // The client interface for setting full duplex transaction: the API checks that it is possible to have the 2 transactions done in parallel.

        // It does not check if the channel supports full duplex, so the transaction may still fail at queuing time.

        inline TInt SetFullDuplexTrans(TIicBusTransfer* aFdTrans);

		inline TInt RemoveTrans(TIicBusTransfer* aTrans);

		// Client interface to explicitly disassociate transfer lists from the transaction, when the 

		// transaction is in state EFree.

		// These methods are for optional use. If the transfer list will not be further accessed,

		// then there is no need to explicitly disassociate it from a transaction. However, if

		// it will be accessed again its iTransaction pointer will refer to this object, so should

		// be cleared to prevent corruption - and this is the purpose of these methods.

		inline TInt RemoveHalfDuplexTrans();

		inline TInt RemoveFullDuplexTrans();

		// Accessor method to allow PSL access to iFlags to determine transaction type

		inline TUint Flags();

	protected:

		inline TIicBusTransaction(TDes8* aHeader, TIicBusTransfer* aHdTrans, TUint8 aFlags, TInt aPriority=0);

	public:

		inline TUint8 State();

		inline TInt GetBusId();

	private:

		TDes8* iHeader;

		TUint8 iFlags;	// used to indicate if it supports a preamble

		TUint8 iState;

		TInt8 iSpare1;

		TInt8 iSpare2;

#ifdef STANDALONE_CHANNEL

	//iBusId is needed by client when calling QueueTransaction

	public:

		TInt iBusId; 

#else

	private:

		TInt iBusId;

#endif

		TIicBusTransfer* iHalfDuplexTrans;

		TIicBusTransfer* iFullDuplexTrans;

		TIicBusCallback* iCallback;

		NFastSemaphore iSyncNotification;

		TInt iResult;

		friend class DIicBusChannelMaster;

#ifndef STANDALONE_CHANNEL

		friend class DIicBusController;

#endif

		};

/**

@publishedPartner

@prototype 9.6

Class to represent a callback object for use with asynchronous transactions processed by IIC Master channels

@see IicBus

*/

class TIicBusCallback : public TDfc

	{

public:

	inline TIicBusCallback(TIicBusCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority);

	inline ~TIicBusCallback();

private:

    inline static void DfcFunc(TAny* aPtr);

private:

	TIicBusTransaction* iTransaction;

	TInt iBusId;

	TInt iResult;	// the result of this transaction as a system wide error

	TAny* iParam;

	TIicBusCbFn iCallback;

	friend class DIicBusChannelMaster;

	};

// Forward declarations

class DIicBusChannelSlave;

class TIicBusSlaveCallback;

/**

@publishedPartner

@prototype 9.6

Definition of function prototype for a callback function provided by a client

for invocation when an asynchronous event (such as a notification, or completion

of the asynchronous capture of a channel) occurs for a Slave channel.

@see IicBus

*/

typedef void (*TIicBusSlaveCbFn)(TInt	/*aChannelId*/,

								 TInt	/*aReturn*/,

								 TInt   /*aTrigger*/,

								 TInt16 /*aRxWords*/,

								 TInt16 /*aTxWords*/,

								 TAny*	/*aParam*/);

/**

@publishedPartner

@prototype 9.6

A Slave callback notification object.

It wraps a DFC in client's thread which is queued by the channel generic implementation

when the transfer are completed asynchronously (e.g. in ISR).