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