// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of "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:

// This file implements a loopback driver for use with the ETel Regression test harness.  This

// driver supports two ports with signalling capabilities for DCD, DSR, DTR, RTS, RI, and CTS.

// In order for the signalling to function properly, one port should be opened as a DCE, though

// the driver will allow both ports to operate as DTE's.

// By default, the driver marks or asserts (sets to 1) the following signals when the method

// SetRole is called.

// For the DTE:

// KSignalRTS	KSignalDTR

// For the DCE:

// KSignalCTS	KSignalDSR

// Note that the DCE does NOT set DCD, thus it's initial state is space or de-asserted

// (set to zero).  This was chosen because of the desire of test script authors to fully

// control DCD.

// The driver supports the following signalling configuration handshake capabilities:

// For the DTE:

// KCapsObeyCTSSupported  KCapsFailCTSSupported

// KCapsObeyDSRSupported  KCapsFailDSRSupported

// KCapsObeyDCDSupported  KCapsFailDCDSupported

// For the DCE:

// KCapsObeyRTSSupported  KCapsObeyDTRSupported

// Break, Configuration Change Notification, Flow Control Notification, and Data Available

// Notifications are not supported.

// directory exists.  The log file is named loopback.

// 

//

/**

 @file

 @note	This driver will create a log file in the Logs\ETel directory if the Logs\ETel

*/

#include <cs_port.h>

#include "LOGGER.H"

#include <d32comm.h>

#include <c32comm.h>

#include <e32hal.h>

#include <c32comm_internal.h>

#ifdef __LOGGER__XTRA

#define LOGI(AAA)	CETelLogger::WriteFormat(TRefByValue<const TDesC8>(AAA),iPortName,iSignals,&iPtr);

#else

#define LOGI(AAA)

#endif

#if defined(__VC32__) && _MSC_VER==1100

// Disable MSVC++ 5.0 aggressive warnings about non-expansion of inline functions.

#pragma warning(disable : 4710)	// function '...' not expanded

#endif

const TUint KCommLowUnit=0;

const TUint KBufferGrowthIncrement=0x1000;

const TUint KMaxBufferSize = 0x8000;

// This should be even

const TUint KLoopbackCount=8;

#define SERIAL_DESCRIPTION _L("Loopback CSY")

#define SERIAL_NAME _S("Loopback")

// #define _DEBUG_CONSOLE_

#if defined(_DEBUG_CONSOLE_)

// This class is not used in the loopback csy.  It is left here for future reference.

#include <e32twin.h>

class RDebugConsole : public RConsole

	{

public:

	RDebugConsole();

public:

	void Printf(TRefByValue<const TDesC> aFmt,...);

	};

#define DEBUG_TRACE(m) m

#else	// (_DEBUG)

#define DEBUG_TRACE(m)

//

#endif

//

// "Entry point object" makes the objects which do the work

class CHWPort;

/**

 * This class is the factory port object.  It drives the "entry point object" which

 * makes the reset of the objects do their work.  It is based on the basic serial port

 * class CSerial.

 */

class CHWPortFactory : public CSerial

	{

public:

    CHWPortFactory();

    ~CHWPortFactory();

	virtual CPort * NewPortL(const TUint aUnit);

	virtual void Info(TSerialInfo &aSerialInfo);

	void Remove(CHWPort* aPort);

public: //CSerial

	TSecurityPolicy PortPlatSecCapability(TUint aPort) const;

private:

	CHWPort* iPort[KLoopbackCount];	// pairs of ports

	CHWPort* PairedPort(TUint aPort) { return iPort[aPort^1]; } // returns the other half

	};

/**

 *	This class is the object that interfaces with the commserver.  An instance of this class

 *	represents one port in the loopback driver.

 */

class CHWPort : public CPort

	{

public:

	static CHWPort * NewL(TUint aUnit);

private:

	 CHWPort();

public:

	virtual void StartRead(const TAny* aClientBuffer,TInt aLength);

	virtual void ReadCancel();

	virtual TInt QueryReceiveBuffer(TInt& aLength) const;

	virtual void ResetBuffers(TUint aFlags);

	virtual void StartWrite(const TAny* aClientBuffer,TInt aLength);

	virtual void WriteCancel();

	virtual void Break(TInt aTime);

	virtual void BreakCancel();

	virtual TInt GetConfig(TDes8& aDes) const;

	virtual TInt SetConfig(const TDesC8& aDes);

	virtual TInt SetServerConfig(const TDesC8& aDes);

	virtual TInt GetServerConfig(TDes8& aDes);

	virtual TInt GetCaps(TDes8& aDes);

	virtual TInt GetSignals(TUint& aSignals);

	virtual TInt SetSignalsToMark(TUint aSignals);

	virtual TInt SetSignalsToSpace(TUint aSignals);

	virtual TInt GetReceiveBufferLength(TInt& aLength) const;

	virtual TInt SetReceiveBufferLength(TInt aSignals);

	virtual void Destruct();

	virtual void FreeMemory();

	virtual void NotifySignalChange(TUint aSignalMask);

	virtual void NotifySignalChangeCancel();

	virtual void NotifyConfigChange();

	virtual void NotifyConfigChangeCancel();

	virtual void NotifyFlowControlChange();

	virtual void NotifyFlowControlChangeCancel();

	virtual void NotifyBreak();

	virtual void NotifyBreakCancel();

	virtual void NotifyDataAvailable();

	virtual void NotifyDataAvailableCancel();

	virtual void NotifyOutputEmpty();

	virtual void NotifyOutputEmptyCancel();

	virtual TInt GetFlowControlStatus(TFlowControl& aFlowControl);

	virtual TInt GetRole(TCommRole& aRole);

	virtual TInt SetRole(TCommRole aRole);

	virtual ~CHWPort();

#if defined (_DEBUG_DEVCOMM)

	virtual void DoDumpDebugInfo(const RMessage2 &aMessage);

#endif

public:

	void SetLoopbackPort(CHWPort* aHWPort);

	TInt WriteBuf(const TAny* aClientBuffer,TInt aLength, TBool& aIssueComplete);

	void TryToCompleteRead();

	void UpdatePortResources();

private:

	void CheckSigsAndCompleteRead();

public:

	TPtr8 iPtr;				//< A pointer to the buffer created during class creation.

private:

	TCommRole iRole;		//< The role of this port (ECommRoleDTE or ECommRoleDCE)

	TUint iSignals;			//< The current signals for this port

	TUint iSignalMask;		//< The mask used when a NotifySignalChange request is posted.

							//< If it is clear, no request is outstanding.  It is cleared when

							//< a request is either cancelled or completed.

	TBool iWritePending;			//< True if a write is left pending

	TInt  iWritePendingLength;		//< The length of the buffer that was left pending.

	const TAny* iClientWriteBuffer; //< The buffer pointer that was pended.  A pended write

									//< implies that the WriteCompleted was NOT called when

									//< the write was posted.

	TPckgBuf<TCommServerConfigV01> iServerConfig;	//< A placeholder; no real function in loopback.

	TPckgBuf<TCommConfigV01> iConfig;	//< The configuration of this port.  Important fields for

										//< the loopback driver are: iHandShake

	CHWPort* iLoopbackPort;	//< The pointer to the loopback port to which this port is connected.

	/**

	An HBufC created during port creation, pointed to by iPtr.

	This buffer is only appended to by this object on a write request;

	this object never reads from the buffer.  iLoopbackPort is the

	object responsible for reading from this iBuf (via iPtr), and send

	the data it reads to iLoopbackPort's client (as a completion of a

	read request).

	*/

	HBufC8* iBuf;			//< An HBuf created during port creation, pointed to by iPtr.

							//< Note that this buffer can grow during operation, but it will

							//< not shrink.

	TInt iBufSize;			//< The initial size of the buffer and it's growth increment.

	TBool iReadPending;		//< Boolean indicating that a read has been left pending for later

							//< completion.

	TBool iReadOneOrMore;	//< Should the current read (even if it is pending) complete before

							//< the buffer is full?

	TBool iDataNotify;		//< Set when a data notify event is pending

	TInt iBytesWritten;		//< The number of bytes written to the current read buffer.

	TInt iPendingLength;	//< Count of how many more bytes can be written to the read buffer

	/**

	Pointer to the client buffer to be filled by a read.  The read

	actually takes the data from iLoopbackPort->iPtr to send to the

	client.

	*/

	const TAny* iClientReadBuffer;		//< Pointer to the client buffer to be filled by a read.

	TUint iPortName;		//< Unit number of this port

#if defined (_DEBUG_CONSOLE_)

	// Not used in the current loopback driver.

#if defined (_DEBUG_DEVCOMM)

	CCommDebugDumper *iDumper;		//< Pointer to debug class.

#endif

public:

	RDebugConsole iConsole;			//< Console for debugging.

#endif

	};

//

// CHWPort definitions

//

CHWPort::CHWPort() : iPtr(NULL,0,0)

/**

 * This method is the basic constructor for the CHWPort class.  In initializes

 * the iPtr member specifically to NULL.

 *

 * @param	None

 *

 * @return	None

 */

	{

	__DECLARE_NAME(_S("CHWPort"));

	}

void CloseObject(TAny* anObject)

/**

 * This method simply closes an object from the cleanup stack.  The object must contain

 * a Close method.

 *

 * @param	anObject - a TAny pointer to the object to close.

 * @return	None

 */

	{

	((CObject*)anObject)->Close();

	}

CHWPort* CHWPort::NewL(TUint aUnit)

/**

 * This method is used by the factory object to create the new CHWPort instances.

 * After newing the CHWPort object, the buffer is created, roles and signals are defaulted,

 * and names are initialized.

 *

 * @param	aUnit - the unit to create.

 *

 * @return	A pointer to the created object

 */

	{

	LOGTEXTREL(_S8("Loopback:NewL: Called"));

	LOGTEXTREL2(_L8("Loopback:NewL:  Unit %d..."), aUnit);

	CHWPort *p=new(ELeave) CHWPort;

	TCleanupItem closePort(CloseObject,p);

	CleanupStack::PushL(closePort);

	p->iBuf=HBufC8::NewL(KBufferGrowthIncrement);

	p->iBufSize=KBufferGrowthIncrement;

	p->iPtr.Set((TUint8*)p->iBuf->Ptr(),0,KBufferGrowthIncrement);

	p->iRole = ECommRoleDTE;

	p->iSignals = 0;		// start with no signals asserted.

	p->iSignalMask = 0;		// Prevents any spurrious notifications, etc.

	TName name;

	name.Format(_L("%d"),aUnit);

	p->SetName(&name);

	p->iPortName = aUnit;

#if defined (_DEBUG_CONSOLE_)

	name.Format(_L("Comm::%d"),aUnit);

	p->iConsole.SetTitle(name);

#if defined (_DEBUG_DEVCOMM)

	p->iDumper=CCommDebugDumper::NewL(p->iConsole);

#endif

#endif

	CleanupStack::Pop();

	return p;

	}

void CHWPort::SetLoopbackPort(CHWPort* aHWPort)

/**

 * This method sets up the loopback port member of the CHWPort.  It is used after

 * both ports have been created (NewL).  This allows each port to "know" to whom he is

 * connected.

 *

 * @param	aHWPort - the port which THIS port should be connected to.

 *

 * @return	None

 */

	{

	if (aHWPort != NULL)

		{

		LOGTEXT3(_L8("SetLoopbackPort:  Unit %d-%d"), iPortName, aHWPort->iPortName);

		}

	else

		{

		LOGTEXT2(_L8("Loopback:SetLoopbackPort:  Unit %d..."), iPortName);

		}

	// Now set up the loopback

	iLoopbackPort=aHWPort;

	}

void CHWPort::CheckSigsAndCompleteRead()

/**

 * This method checks the configuration of the port and the current state of the signals

 * and determines if the read should even attempt to be completed.  Based on configurations,

 * reads can fail or be left pending (KConfigObeyXXX).  This method calls TryToCompleteRead

 * if all configuration and signal state allows the read to continue.

 *

 * Note that this method is called to either complete a pended read (from WriteBuf) or

 * to complete an incoming read request (from StartRead).  Also note that this routine does

 * not check the fail flags.  These flags are checked when the read is first posted and

 * when the signals are first asserted/deasserted.  It is unnecessary (and maybe even undesirable)

 * to check the fail flags here.

 *

 * @param	None

 *

 * @return	None

 */

	{

	LOGI(_L8("CheckSigsAndCompleteRead:%04d %x \"%S\""));

	LOGTEXT2(_L8("Loopback:CheckSigsAndCompleteRead:  Unit %d..."), iPortName);

	// At this point, we must check the config flags and signals.  If we have been

	// configured to obey signals, then we must pend the read and not complete it.

	// Note that the iReadPending flag was set in StartRead().

	if (ECommRoleDTE == iRole)

		{

		if (((iConfig().iHandshake & KConfigObeyDCD) && (!(iSignals & KSignalDCD))) ||

			((iConfig().iHandshake & KConfigObeyDSR) && (!(iSignals & KSignalDSR))))

			{

			LOGI(_L8("CheckSigsAndCompleteRead DTE:%04d %x \"%S\""));

			return;

			}

		}

	else if (ECommRoleDCE == iRole)

		{

		if ((iConfig().iHandshake & (KConfigObeyDTR)) && (!(iSignals & (KSignalDTR))))

			{

			LOGI(_L8("CheckSigsAndCompleteRead DCE:%04d %x \"%S\""));

			return;

			}

		}

	// Can the request be satisfied now?  Note that we call TryToCompleteRead on THIS instance.

	// This means that CheckSigsAndCompleteRead must be called on the desired instance.

	TryToCompleteRead();

	LOGI(_L8("CheckSigsAndCompleteRead:%04d %x \"%S\""));

	}

void CHWPort::StartRead(const TAny* aClientBuffer,TInt aLength)

/**

 * This method queues a read operation to the driver.  If the read length is zero (which is a

 * special case used during initialization) the read completes immediately without being

 * concerned about any of the configuration flags.  Failure flags are checked in this routine.

 * If the port has been configured to fail (KConfigFailXXX) and the signals are NOT asserted,

 * then the read will fail immediately with KErrCommsLineFail.  Obey flags are not handled here,

 * but are handled in a different method.  The code was structured in this manner so that the

 * Obey flags are checked any time a read is attempted to be completed, not just when the read

 * is initially sent to the driver.  This is needed because reads can pend and before the reads

 * are completed the signal state could change.

 *

 * @param	aClientBuffer	- a TAny * to the buffer into which data is placed.

 * @param	aLength			- the length of the buffer.  If the length is less than zero the

 *                            read can be completed with less than length bytes available.  If

 *                            a positive length value is specified, the read will not complete

 *                            until length bytes have been read.

 *

 * @return	None

 */

	{

	//	DEBUG_TRACE((iConsole.Write(_L("DoRead \n\r"))));

	LOGI(_L8("LOGIStartRead:%04d %x \"%S\""));

	LOGTEXT2(_L8("Loopback:StartRead:  Unit %d..."), iPortName);

	// Because a length of zero is a special case, we will complete this without

	// worries about the config/fail flags.

	if(aLength==0)

		{

		ReadCompleted(KErrNone);

		LOGI(_L8("StartRead 0:%04d %x \"%S\""));

		return;

		}

	// At this point, we must check the config flags and signals.  If we have been

	// configured to fail operations if certain signals are not set, then we must

	// fail the read.

	if (ECommRoleDTE == iRole)

		{

		if (((iConfig().iHandshake & KConfigFailDCD) && (!(iSignals & KSignalDCD))) ||

			((iConfig().iHandshake & KConfigFailDSR) && (!(iSignals & KSignalDSR))))

			{

			ReadCompleted(KErrCommsLineFail);

			LOGI(_L8("XtartRead DTE:%04d %x \"%S\""));

			return;

			}

		}

	else if (ECommRoleDCE == iRole)

		{

		if ((iConfig().iHandshake & (KConfigFailDTR)) && (!(iSignals & (KSignalDTR))))

			{

			ReadCompleted(KErrCommsLineFail);

			LOGI(_L8("StartRead DCE:%04d %x \"%S\""));

			return;

			}

		}

	// At this point, we set up for the read.  If the obey flags later don't let us

	// complete the read, having this work done is vital.

	iReadOneOrMore=EFalse;

	if(aLength<0)

		{

		aLength=-aLength;

		iReadOneOrMore=ETrue;

		}

	iBytesWritten=0;

	iPendingLength=aLength;

	iClientReadBuffer=aClientBuffer;

	iReadPending=ETrue;

	// Later code will assert iLoopback, so check it now to avoid crashes during startup.

	// The CheckSigsAndCompeteRead method will actually process the Obey flags.

	if (iLoopbackPort != NULL)

		{

		CheckSigsAndCompleteRead();

		}

	LOGI(_L8("StartRead:%04d %x \"%S\""));

	}

void CHWPort::ReadCancel()

/**

 * Cancel a pending read and complete it with KErrCancel.  The handling of the CActive class

 * will by default complete any outstanding read with KErrCancel, but it is cleaner to handle

 * that processing here.

 *

 * @param	None

 *

 * @return	None

 */

	{

	LOGI(_L8("ReadCancel:%04d %x \"%S\""));

	LOGTEXT2(_L8("Loopback:ReadCancel:  Unit %d..."), iPortName);

	iReadPending=EFalse;

	ReadCompleted(KErrCancel);

	}

TInt CHWPort::WriteBuf(const TAny* aClientBuffer,TInt aLength, TBool& aIssueComplete)

/**

 * This method writes the client buffer to the loopback port.  It must take into consideration

 * all of the KConfigFailXXX and KConfigObeyXXX flags that might have been specified in the

 * configuration of the port.  Any fail configuration results with writes failing with the

 * KErrCommsLineFail error.  This method is used both when the write is originally posted to

 * the driver and when trying to finish any write that was pended by the driver based on the

 * Obey flags.  This routine does not actually complete the read, but returns a value with

 * which the caller should complete the read.  Because this routine can also leave the operation

 * pended, it uses the aIssueComplete boolean to tell the caller whether or not to complete the

 * read.

 *

 * @param	aClientBuffer	- a TAny * to the buffer which contains the data to write

 * @param	aLength			- the length of the buffer.

 * @param	aIssueComplete	- a reference to a boolean used to indicate to the caller if the

 *                            write operation should be completed.

 *							- ETrue  - Caller should issue the WriteCompleted with returned

 *							           result code.

 *							- EFalse - Caller shoud not issue the WriteCompleted.

 *

 * @return	KErrNone		- Everything is okay

 * @return	KErrCommsLineFail  - Write failed based on signal state and configuration.

 * @return	Varies			- Non-Zero return from Kernel calls

 */