// Copyright (c) 1995-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\comm.h

// 

//

/**

 @file

 @internalComponent

*/

#ifndef __M32COMM_H__

#define __M32COMM_H__

#include <platform.h>

#include <kernel/kpower.h>

#include <d32comm.h>

#include <e32ver.h>

//

const TInt KCommsMajorVersionNumber=1;

const TInt KCommsMinorVersionNumber=1;

const TInt KCommsBuildVersionNumber=KE32BuildVersionNumber;

//

const TInt KDefaultRxBufferSize=0x800;

const TInt KTxBufferSize=0x400;

const TInt KMaxHighWaterMark=0x080;

//

/**

	@publishedPartner

	@released

*/

const TUint KReceiveIsrParityError=0x10000000;

/**

	@publishedPartner

	@released

*/

const TUint KReceiveIsrFrameError=0x20000000;

/**

	@publishedPartner

	@released

*/

const TUint KReceiveIsrOverrunError=0x40000000;

/**

	@publishedPartner

	@released

*/

const TUint KReceiveIsrBreakError=0x80000000;

const TUint KReceiveIsrMaskError=0xF0000000;

//

const TInt KTxNoChar=-1;

//

const TUint KReceiveIsrTermChar=0x80000000;

const TUint KReceiveIsrMaskComplete=0xf0000000;

const TUint KReceiveIsrShift=24;

const TUint KReceiveIsrShiftedMask=0x0f;

/**

	@publishedPartner

	@released

*/

const TUint KDTEInputSignals=(KSignalCTS|KSignalDSR|KSignalDCD|KSignalRNG);

/**

	@publishedPartner

	@released

	An enumeration listing the stopping modes supported by this driver, to be passed to the Stop function.

*/

enum TStopMode 

	{

	/**

	Stopping due to normal operational reasons.

	*/

	EStopNormal,

	/**

	Stopping due to system power down.

	*/

	EStopPwrDown,

	/**

	Emergency stop. Deprecated.

	*/

	EStopEmergency

	};

class DChannelComm;

/**

	@publishedPartner

	@released

	An abstract class for a serial comm PDD.

*/

class DComm : public DBase

	{

public:

	/**

	Starts receiving characters.

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

	*/

	virtual TInt Start() =0;

	/**

	Stops receiving characters.

	@param aMode The stopping reason as one of TStopMode.

	@see TStopMode

 	*/

	virtual void Stop(TStopMode aMode) =0;

	/**

	Starts or stop the uart breaking.

	@param aState ETrue to enable break signal(LCR) and EFalse disable break signal(LCR).

	*/

	virtual void Break(TBool aState) =0;

	/**

	Starts transmitting characters.

	*/

	virtual void EnableTransmit() =0;

	/**

	Read and translate the modem control lines.

	@return State changes. 

			For Example:

			RTS, DSR, RI, Carrier Detect.

	*/

	virtual TUint Signals() const =0;

	/**

	Set signals.

	@param aSetMask   A bit mask for those modem control signals which are to be asserted.

	@param aClearMask A bit mask for those modem control signals which are to be de-asserted.

					  Each bit in the bit masks above corresponds to a modem control signal. 

					  Bits are defined as one of:

					  KSignalCTS

					  KSignalDSR

					  KSignalDCD

					  KSignalRNG

					  KSignalRTS

					  KSignalDTR

					  KSignalBreak

	*/

	virtual void SetSignals(TUint aSetMask,TUint aClearMask) =0;

	/**

	Validates a new configuration.

	@param  aConfig Const reference to the comms configuration structure; to hold the configuration settings for serial comm port.

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

	@see TCommConfigV01

	*/

	virtual TInt ValidateConfig(const TCommConfigV01 &aConfig) const =0;

	/**

	Configures the hardware device. This is device specific API, that provides functionality to configure the uart.

	@param aConfig configuration settings for the device.

	@see TCommConfigV01

	*/

	virtual void Configure(TCommConfigV01 &aConfig) =0;

	/**

	Gets the capabilities of the comm PDD.

	@param aCaps On return this descriptor should have been filled with capabilities. 

	*/

	virtual void Caps(TDes8 &aCaps) const =0;

	/**

	Checks the configuration.

	@param aConfig A reference to the structure TCommConfigV01 with configuration to check.

	@see TCommConfigV01

	*/

	virtual void CheckConfig(TCommConfigV01& aConfig)=0;

	/**

	Disable all IRQs.

	@return The state of the interrupts before disable, which is used to restore the interrupt state.

	*/

	virtual TInt DisableIrqs()=0;

	/**

	Restore IRQs to the passed level.

	@param  aIrq The level to restore the IRQs to.

	*/

	virtual void RestoreIrqs(TInt aIrq)=0;

	/**

	Returns a pointer to the DFC queue that should be used by the comm LDD.

	@param 	aUnit Unit for which the DfcQ is retrieved.

	@return A Pointer to the DFC queue that should be used by the USB LDD.

	@see TDfcQue

	*/

	virtual TDfcQue* DfcQ(TInt aUnit)=0;

	/**

	Checks power status.

	@return ETrue if status is good, EFalse otherwise.

	*/

	inline TBool PowerGood();

	inline void SetCurrent(TInt aCurrent);

	inline void ReceiveIsr(TUint* aChar, TInt aCount, TInt aXonXoff);

	inline TInt TransmitIsr();

	inline void CheckTxBuffer();

	inline void StateIsr(TUint aSignals);

	inline TBool Transmitting();

public:

	/**

	Pointer to the logical channel object which is derived from DLogicChannel.

	*/

	DChannelComm *iLdd;

	/**

	A Boolean flag to indicate when transmission is in progress [ETrue=(Trasnmission in progress)].

	*/

	TBool iTransmitting;

	};

/**

@internalComponent

*/

class DDeviceComm : public DLogicalDevice

	{

public:

	DDeviceComm();

	virtual TInt Install();

	virtual void GetCaps(TDes8 &aDes) const;

	virtual TInt Create(DLogicalChannelBase*& aChannel);

	};

//

// TClientSingleBufferRequest

//

class TClientSingleBufferRequest

{

public:

	TClientSingleBufferRequest() 

		{

		Reset();

		}

	~TClientSingleBufferRequest() 

		{

		if (iBufReq)

			Kern::DestroyClientBufferRequest(iBufReq);

		Reset();

		}

	void Reset()

		{

		iBufReq = NULL;

		iBuf = NULL;

		iLen = 0;

		}

	TInt Create()

		{

		if (iBufReq)

			return KErrNone;

		TInt r = Kern::CreateClientBufferRequest(iBufReq, 1, TClientBufferRequest::EPinVirtual);

		return r;

		}

	TInt Setup(TRequestStatus* aStatus, TAny* aDes, TInt aLen=0) 

		{

		TInt r = iBufReq->Setup(iBuf, aStatus, aDes);

		if (r == KErrNone)

			iLen = aLen;

		return r;

		}

	TInt SetupFromPtr(TRequestStatus* aStatus, TLinAddr aPtr, TInt aLen) 

		{

		TInt r = iBufReq->Setup(iBuf, aStatus, aPtr, aLen);

		iLen = aLen;

		return r;

		}

	void Complete(DThread* aClient, TInt aReason) 

		{

		if (iBufReq)

			{

			iBuf = NULL;

			Kern::QueueBufferRequestComplete(aClient, iBufReq, aReason);

			}

		}

	TClientBufferRequest* iBufReq;

	TClientBuffer* iBuf;

	TInt iLen;

};

class DCommPowerHandler;

/**

@internalComponent

*/

class DChannelComm : public DLogicalChannel

	{

public:

	enum TState {EOpen,EActive,EClosed};

	enum TRequest {ERx=1, ETx=2, ESigChg=4, EBreak=8, EAll=0xff};

	DChannelComm();

	~DChannelComm();

	virtual void ReceiveIsr(TUint* aChar, TInt aCount, TInt aXonXoff);

	virtual void CheckTxBuffer();

	virtual void StateIsr(TUint aSignals);

	virtual TInt TransmitIsr();

	virtual TInt RequestUserHandle(DThread* aThread, TOwnerType aType);

	/**	@publishedPartner

		@released */

	virtual void UpdateSignals(TUint aSignals);

	inline void SetStatus(TState aStatus);

	virtual TInt SendMsg(TMessageBase* aMsg);

protected:

	virtual TInt DoCreate(TInt aUnit, const TDesC8* anInfo, const TVersion& aVer);

	virtual void HandleMsg(TMessageBase* aMsg);

	void DoCancel(TInt aMask);

	TInt DoControl(TInt aId, TAny* a1, TAny* a2);

	void DoRequest(TInt aId, TAny* a1, TAny* a2);

	void DoPowerUp();

	void Start();

	TInt Shutdown();

	void BreakOn();

	void BreakOff();

	void AssertFlowControl();

	void ReleaseFlowControl();

	TInt SetRxBufferSize(TInt aSize);

	void ResetBuffers(TBool aResetTx);

	void DoDrainRxBuffer(TInt aEndIndex);

	void DoFillTxBuffer();

	void DoCompleteRx();

	void DoCompleteTx();

	void Complete(TInt aMask, TInt aReason);

	inline void DrainRxBuffer()	{ iRxDrainDfc.Add(); }

	inline void RxComplete();

	inline void TxComplete();

protected:

	inline void EnableTransmit();

	inline TInt IsLineFail(TUint aFailSignals);

	inline TInt PddStart();

	inline void Stop(TStopMode aMode);

	inline void PddBreak(TBool aState);

	inline TUint Signals() const;

	inline void SetSignals(TUint aSetMask,TUint aClearMask);

	inline TInt ValidateConfig(const TCommConfigV01 &aConfig) const;

	inline void PddConfigure(TCommConfigV01 &aConfig);

	inline void PddCaps(TDes8 &aCaps) const;

	inline void PddCheckConfig(TCommConfigV01& aConfig);

	inline TBool Transmitting();

private:

	static void PowerUpDfc(TAny* aPtr);

	static void PowerDownDfc(TAny* aPtr);

	static void DrainRxDfc(TAny* aPtr);

	static void FillTxDfc(TAny* aPtr);

	static void CompleteRxDfc(TAny* aPtr);

	static void CompleteTxDfc(TAny* aPtr);

	static void TimerDfcFn(TAny* aPtr);

	static void SigNotifyDfc(TAny* aPtr);

	void TimerDfc();

	static void MsCallBack(TAny* aPtr);

	inline TBool IsTerminator(TUint8 aChar);

	inline void SetTerminator(TUint8 aChar);

	inline TInt RxCount();

	inline TInt TxCount();

	inline TBool AreAnyPending() const;

	void InitiateRead(TInt aLength);

	void InitiateWrite();

	void DoSigNotify();

	void UpdateAndProcessSignals();

	TUint FailSignals(TUint aHandshake);

	TUint HoldSignals(TUint aHandshake);

	TUint FlowControlSignals(TUint aHandshake);

	TUint AutoSignals(TUint aHandshake);

	TInt SetConfig(TCommConfigV01& aConfig);

	void CheckOutputHeld();

	void RestartDelayedTransmission();

	static void FinishBreak(TAny* aSelf); // Called when timer indicating break should finish expires

	void QueueFinishBreakDfc();	// Called to queue dfc to finish break

	static void FinishBreakDfc(TAny* aSelf); // Dfc called to finish break

	void FinishBreakImplementation(TInt aError); // Actual implementation to finish break

public:

	// Port configuration

	TCommConfigV01 iConfig;

	/**	@publishedPartner

		@released */

	TUint iRxXonChar;

	/**	@publishedPartner

		@released */

	TUint iRxXoffChar;

	TInt TurnaroundSet(TUint aNewTurnaroundMilliSeconds);

	TBool TurnaroundStopTimer();

	TInt TurnaroundClear();

	TInt RestartTurnaroundTimer();

	static void TurnaroundStartDfc(TAny* aSelf);

	void TurnaroundStartDfcImplementation(TBool inIsr);

	static void TurnaroundTimeout(TAny* aSelf);

	void TurnaroundTimeoutImplementation();

	// General items

	DThread* iClient;

	DCommPowerHandler* iPowerHandler;

	TDfc iPowerUpDfc;

	TDfc iPowerDownDfc;

	TState iStatus;

	TDfc iRxDrainDfc;

	TDfc iRxCompleteDfc;

	TDfc iTxFillDfc;

	TDfc iTxCompleteDfc;

	TDfc iTimerDfc;

	TDfc iSigNotifyDfc;

	TUint iFlags;				//

	TUint iSignals;				// State of handshake lines

	TUint iFailSignals;			// 1 bit means line low causes line fail error

	TUint iHoldSignals;			// 1 bit means line low halts TX

	TUint iFlowControlSignals;	// 1 bit means signal is used for RX flow control

	TUint iAutoSignals;			// 1 bit means signal is high when channel is open

	TUint8 iTerminatorMask[32];	// 1 bit means character is a terminator

	TUint8 iStandby;			// ETrue means the machine is transiting to/from standby

	TUint8 iMsgHeld;			// ETrue means a message has been held up waiting the end of from standby transition 

	// Min Turnaround time between Rx and Tx

	TUint		iTurnaroundMicroSeconds;		// delay after a receive before transmission in us

	TUint		iTurnaroundMinMilliSeconds;		// delay after a receive before transmission in ms

	TUint       iTurnaroundTimerStartTime;      // stores the start time of the turnaround timer.

	TUint8      iTurnaroundTimerStartTimeValid; // stores turnaround timer status 0 after boot, 1 if the timestamp is valid, and 2 if invalid

	TUint8		iTurnaroundTimerRunning;		// a receive has started the timer

	TUint8		iTurnaroundTransmitDelayed;		// a transmission is held until time elapses after a receive

	TUint8		iSpare;

	NTimer	iTurnaroundTimer;				// used to delay transmission after a receive

	TDfc		iTurnaroundDfc;					// used in interrupt space, to trigger a call in user space

	// RX buffer related items

	TUint8 *iRxCharBuf;			// stores received characters

	TInt iRxBufSize;			// Size of the LDD receive buffer. 

	TUint8 *iRxErrorBuf;		// stores received character error status

	volatile TInt iRxPutIndex;	// Index for next RX char to be stored

	TInt iRxGetIndex;			// Index for next RX char to be retrieved

	TInt iFlowControlLowerThreshold;	// release flow control threshold

	TInt iFlowControlUpperThreshold;	// assert flow control threshold

	TInt iRxDrainThreshold;				// drain rx buffer before completion threshold

	TInt iRxBufCompleteIndex;	// One after last char to be forwarded due to completion

	TBool iInputHeld;			// TRUE if we have asserted flow control

	// RX client related items

	TClientSingleBufferRequest iRxBufReq;

	TInt iRxDesPos;				// pos of next char to be stored in client descriptor

	TUint8 iRxOutstanding;		// TRUE if a client read is outstanding

	TUint8 iNotifyData;			// TRUE if data available notifier outstanding

	TInt iRxError;

	NTimer iTimer;				// timer for ReadOneOrMore

	TInt iTimeout;				// timeout period for ReadOneOrMore

	TInt iRxOneOrMore;

	// TX buffer related items

	TUint8 *iTxBuffer;			// stores characters awaiting transmission

	TInt iTxPutIndex;			// Index for next TX char to be stored

	volatile TInt iTxGetIndex;	// Index for next TX char to be output

	TInt iTxBufSize;

	TInt iTxFillThreshold;		// fill tx buffer threshold

	TInt iOutputHeld;			// bits set if peer has asserted flow control

	TInt iJamChar;				// character to jam into TX output stream

	// TX client related items

	TClientSingleBufferRequest iTxBufReq;

	TInt iTxDesPos;				// pos of next char to be fetched from client descriptor

	TBool iTxOutstanding;		// TRUE if a client write is outstanding

	TInt iTxError;

	// Signal change notification

	TUint iNotifiedSignals;

	TUint iSigNotifyMask;

	TClientDataRequest<TUint>* iSignalsReq;

	// hackery

	TVirtualPinObject* iPinObjSetConfig;

	TInt iReceived;

	// Break related items

	TInt		 iBreakTimeMicroSeconds;

	TTickLink iBreakTimer; // Used to time how long the break should last for

	TDfc		 iBreakDfc;	

	TClientRequest* iBreakStatus;

	TBool		iBreakDelayedTx;

	TBool		iTurnaroundBreakDelayed;

	TSpinLock iLock;

	};

/**

@internalComponent

*/

class DCommPowerHandler : public DPowerHandler

	{

public: // from DPOwerHandler

	void PowerUp();

	void PowerDown(TPowerState);

public:

	DCommPowerHandler(DChannelComm* aChannel);

public:

	DChannelComm* iChannel;

	};

#include <drivers/comm.inl>

#endif