/*

* Copyright (c) 2009-2010 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:

*

*/

#ifndef __T_DMA2_H__

#define __T_DMA2_H__

#include "cap_reqs.h"

#include "test_thread.h"

#include "d_dma2.h"

#include <e32std.h>

class TTestCase;

// Global array of test cases

extern RPointerArray<TTestCase> TestArray;

extern RPointerArray<TTestCase> TestArrayCallback;

extern RPointerArray<TTestCase> TestArrayIsrReque;

extern RPointerArray<TTestCase> TestArrayMultiPart;

extern RPointerArray<TTestCase> TestArrayIsrAndDfc;

extern RPointerArray<TTestCase> TestArrayBenchmark;

extern RPointerArray<TTestCase> TestArray2DTest;

extern RPointerArray<TTestCase> TestArrayIsrAndDfc;

extern RPointerArray<TTestCase> TestArrayChannel;

extern RPointerArray<TTestCase> TestArraySuspend;

extern RPointerArray<TTestCase> TestArrayQueue;

extern RPointerArray<TTestCase>	TestArraySimple;

extern RPointerArray<TTestCase>	TestArrayRequest;

extern RPointerArray<TTestCase>	TestArrayFragment;

extern TBool gVerboseOutput;   // Verbose output control

const TInt KParameterTextLenMax = 80;	// command-line param length

/**

This function prints out the PSL test Information

*/

void Print(const TDmaV2TestInfo& aInfo);

/**

Runs all framework self tests

*/

void SelfTests();

class CSingleTransferTest;

class CIsrRequeTest;

class CMultiTransferTest;

/**

An interface to a classs that sets up the buffers before a test

*/

class MPreTransfer

	{

public:

	virtual ~MPreTransfer()

		{}

	virtual void Setup(const CSingleTransferTest& aTest) const = 0;

	virtual void Setup(const CIsrRequeTest& aTest) const = 0;

	virtual void Setup(const CMultiTransferTest& aTest) const = 0;

	};

/**

An interface for a check which takes place at the end of a DMA

transfer test to verify the transfer was as expected.

*/

class MPostTransferCheck

	{

public:

	virtual ~MPostTransferCheck()

		{}

	virtual TInt Check(const CSingleTransferTest& aTest) const = 0;

	virtual TInt Check(const CIsrRequeTest& aTest) const = 0;

	virtual TInt Check(CMultiTransferTest& aTest) const = 0;

	};

class TCompare2D : public MPostTransferCheck

	{

public:

	TCompare2D()

		{}

	virtual TInt Check(const CSingleTransferTest& aTest) const;

	virtual TInt Check(const CIsrRequeTest& aTest) const;

	virtual TInt Check(CMultiTransferTest& aTest) const;

	};

class TAlwaysFail : public MPostTransferCheck

	{

public:

	virtual TInt Check(const CSingleTransferTest& /*aTest*/) const

		{return KErrUnknown;}

	virtual TInt Check(const CIsrRequeTest&) const

		{return KErrUnknown;}

	virtual TInt Check(CMultiTransferTest&) const

		{return KErrUnknown;}

	};

class TAlwaysPass : public MPostTransferCheck

	{

public:

	virtual TInt Check(const CSingleTransferTest& /*aTest*/) const

		{return KErrNone;}

	virtual TInt Check(const CIsrRequeTest&) const

		{return KErrNone;}

	virtual TInt Check(CMultiTransferTest&) const

		{return KErrNone;}

	};

/**

Compare that all the various source buffers of a test match

its destination buffers

*/

class TCompareSrcDst : public MPostTransferCheck

	{

public:

	TCompareSrcDst()

		{}

	virtual TInt Check(const CSingleTransferTest& aTest) const;

	virtual TInt Check(const CIsrRequeTest& aTest) const;

	virtual TInt Check(CMultiTransferTest& aTest) const;

protected:

	TInt Check(const TIsrRequeArgsSet& aRequeueArgSet, TUint8* aChunkBase, const TDmaTransferArgs& aTferArgs) const;

	TInt Check(const TIsrRequeArgs& aRequeueArgs) const;

	TInt Check(const TDmaTransferArgs& aTransferArgs, TUint8* aChunkBase) const;

	};

/**

Check whether destination buffers are zero filled

Used to check that a transfer hasn't taken place.

*/

class TCheckNoTransfer : public MPostTransferCheck

	{

public:

	TCheckNoTransfer()

		{}

	virtual TInt Check(const CSingleTransferTest& aTest) const;

	virtual TInt Check(const CIsrRequeTest& aTest) const;

	virtual TInt Check(CMultiTransferTest& aTest) const;

protected:

	TBool IsZeroed(const TDmaTransferArgs& aTransferArgs, TUint8* aChunkBase) const;

	};

/**

Base class for all DMA tests

*/

class CDmaTest : public CTest

	{

public:

	CDmaTest(const TDesC& aName, TInt aIterations, const MPreTransfer* aPreTransfer, const MPostTransferCheck* aPostTransfer)

		: CTest(aName, aIterations), iPreTransfer(aPreTransfer), iPostTransferCheck(aPostTransfer)

		{}

	void OpenDmaSession();

	/* Duplicate aSession */

	void OpenDmaSession(const RDmaSession& aSession);

	void CloseDmaSession();

	void ChannelPause(const TUint aChannelSessionCookie);

	void ChannelResume(const TUint aChannelSessionCookie);

	virtual void PrintTestInfo() const;

	virtual TBool Result() = 0;

	const RChunk& Chunk() const

		{return iChunk;}

	/**

	Tells the test which DMA channel it should run on

	*/

	void SetChannelCookie(TUint32 aCookie)

		{iChannelCookie = aCookie;}

	virtual void PreTransferSetup();

	virtual TInt DoPostTransferCheck();

protected:

	RDmaSession iDmaSession;

	RChunk iChunk;

	/**

	Identifies the channel to open (as understood by a DMA PSL)

	*/

	TUint iChannelCookie;

	const MPreTransfer* iPreTransfer;

	const MPostTransferCheck* iPostTransferCheck; //!< Some check to be run after the transfer

	};

/**

The Decorator Pattern is used allowing test classes to be optionally extended

using wrapper/decorator classes.

This is the base class for test decorators

*/

class CDmaTestDecorator : public CDmaTest

	{

public:

protected:

	CDmaTestDecorator(CDmaTest* aDecoratedTest);

	CDmaTestDecorator(const CDmaTestDecorator& aOther);

	CDmaTest* iDecoratedTest;

	};

/**

Will run the wrapped test against both versions of the DMA

API if available, otherwise just the old version.

*/

class CMultiVersionTest : public CDmaTestDecorator

	{

public:

	CMultiVersionTest(CSingleTransferTest* aDmaTest); 

	CMultiVersionTest(const CMultiVersionTest& aOther);

	~CMultiVersionTest();

	virtual void Announce() const;

	virtual void PrintTestType() const;

	virtual void PrintTestInfo() const; 

	virtual CTest* Clone() const {return new CMultiVersionTest(*this);}

	virtual void SetupL();

	virtual void RunTest();

	virtual TBool Result();

protected:

	void Configure();

	TBool Version2PILAvailable();

	CSingleTransferTest* iNewVersionTest;

	};

/**

Holds return codes for the various functions which must be called

to create, fragment, and queue a DMA request

*/

struct TRequestResults

	{

	TRequestResults

		(

		TInt aCreate = KErrNone,

		TInt aFragmentCount = 0,

		TInt aFragmentationResult = KErrNone,

		TInt aQueueResult = KErrNone

		)

		:iCreate(aCreate), 

		 iFragmentCount(aFragmentCount), 

		 iFragmentationResult(aFragmentationResult), 

		 iQueueResult(aQueueResult)

		{}

	/**

	Constructs with error results

	*/

	TRequestResults(TFalse)

		:iCreate(KErrUnknown), 

		 iFragmentCount(0), 

		 iFragmentationResult(KErrUnknown), 

		 iQueueResult(KErrUnknown)

		{}

	inline TRequestResults& CreationResult(TInt aErrorCode) {iCreate = aErrorCode; return *this;}

	inline TRequestResults& FragmentCount(TInt aCount) {iFragmentCount = aCount; return *this;}

	inline TRequestResults& FragmentationResult(TInt aErrorCode) {iFragmentationResult = aErrorCode; return *this;}

	inline TRequestResults& QueueResult(TInt aErrorCode) {iQueueResult = aErrorCode; return *this;}

	TInt iCreate;

	TInt iFragmentCount; //!< 0 means any result permitted

	TInt iFragmentationResult;

	TInt iQueueResult;

	};

/**

Holds all the results for a DMA CSingleTransferTest

*/

struct TResultSet

	{

	/**

	No errors expected

	*/

	TResultSet(TInt aChannelOpenResult = KErrNone,

			const TRequestResults aRequestResults = TRequestResults(),

			TInt aPostTransferCheck = KErrNone,

			const TCallbackRecord aCallbackRecord = TCallbackRecord(TCallbackRecord::EThread,1)

			)

		:

		iChannelOpenResult(aChannelOpenResult),

		iRequestResult(aRequestResults),

		iPostTransferCheck(aPostTransferCheck),

		iCallbackRecord(aCallbackRecord)

		{}

	explicit TResultSet(const TCallbackRecord& aRecord)

		:iChannelOpenResult(KErrNone),

		 iRequestResult(),

		 iPostTransferCheck(KErrNone),

		 iCallbackRecord(aRecord)

		{}

	/**

	Errors expected

	*/

	TResultSet(TFalse)

		:iChannelOpenResult(KErrUnknown), 

		iRequestResult(EFalse),

		iPostTransferCheck(KErrUnknown),

		iCallbackRecord(TCallbackRecord::Empty())

		{}		

	void Print() const;

	TBool operator == (const TResultSet& aOther) const;

	/** Set channel opening result */

	TResultSet& ChannelOpenResult(TInt aResult) {iChannelOpenResult = aResult; return *this;}

	TResultSet& PostTransferResult(TInt aResult) {iPostTransferCheck = aResult; return *this;}

	/** Set request results */

	TResultSet& RequestResult(const TRequestResults& aResults) {iRequestResult = aResults; return *this;}

	/** Set Callback record */

	TResultSet& CallbackRecord(const TCallbackRecord& aCallbackRecord) {iCallbackRecord = aCallbackRecord; return *this;}

	TInt iChannelOpenResult;

	TRequestResults iRequestResult;

	TInt iPostTransferCheck;

	TCallbackRecord iCallbackRecord;

	};

/**

Fills each source buffer with an increasing value and clears each destination

*/

class TPreTransferIncrBytes : public MPreTransfer

	{

public:

	TPreTransferIncrBytes()

		{}

	virtual void Setup(const CSingleTransferTest& aTest) const;

	virtual void Setup(const CIsrRequeTest& aTest) const;

	virtual void Setup(const CMultiTransferTest& aTest) const;

	static void SelfTest();

protected:

	virtual void Setup(const TAddressParms& aParams) const;

	TBool CheckBuffers(const CIsrRequeTest& aTest) const;

	TBool CheckBuffers(const CMultiTransferTest& aTest) const;

	TBool CheckBuffers(const RArray<const TAddressParms>& aTransferParams, TBool aAllowExactRepeat=ETrue) const;

	// This function is part of the unit test

	friend TBool DoTferParmTestL(const TAddressParms* aParms, TInt aCount, TBool aAllowRepeat, TBool aPositive);

	};

const TPreTransferIncrBytes KPreTransferIncrBytes;

const TCompareSrcDst KCompareSrcDst;

const TCompare2D KCompare2D;

const TCheckNoTransfer KCheckNoTransfer;

/**

Iterates over the bytes in buffer, in the order

the supllied DMA config would access them

*/

class TTransferIter

	{

public:

	TTransferIter()

		:iCfg(NULL), iPtr(NULL)

		{}

	TTransferIter(const TDmaTransferConfig& aCfg, TUint8* aChunkBase=NULL)

		:iElem(0), iFrame(0), iCfg(&aCfg), iChunkBase(aChunkBase), iPtr(Start()), iBytes(0)

		{}

	void operator++ ();

	TUint8& operator* ()

		{

		Invariant();

		return *iPtr;

		}

	TBool operator!= (const TTransferIter& aOther)

		{

		return (iPtr != aOther.iPtr);

		}

	static void SelfTest();

private:

	TUint8* Start() const

		{

		return iChunkBase + iCfg->iAddr;

		}

	void Invariant() const;

	TUint iElem; //!< The current element

	TUint iFrame; //!< The current frame

	const TDmaTransferConfig* const iCfg;

	TUint8* iChunkBase;

	TUint8* iPtr; //<! Pointer to the current byte

	TUint iBytes; //!< The number of bytes traversed

	};

/**

Performs a single DMA transfer using the member TDmaTransferArgs on

one channel. At each stage of the transfer results are recorded in a

TResultSet struct: at the end these are compared with a set of expected

results.

*/

class CSingleTransferTest : public CDmaTest

	{

public:

	CSingleTransferTest(

			const TDesC& aName, TInt aIterations,

			const TDmaTransferArgs& aArgs,

			const TResultSet& aExpected,

			TUint aMaxFragmentSize = 0,

			const MPostTransferCheck* aPostTferChk = &KCompareSrcDst,

			const MPreTransfer* aPreTfer = &KPreTransferIncrBytes

			)

		: CDmaTest(aName, aIterations, aPreTfer, aPostTferChk),

		iTransferArgs(aArgs),iExpected(aExpected),iActual(EFalse),

		iUseNewRequest(ETrue),

		iUseNewFragment(ETrue),

		iMaxFragmentSize(aMaxFragmentSize)

		{}

	/**

	Perform each stage of trasnfer

	*/

	virtual void RunTest();

	virtual void PrintTestType() const;

	virtual void PrintTestInfo() const;

	virtual CTest* Clone() const {return new CSingleTransferTest(*this);}

	/**

	Compares the actual vs the exepected results and reports

	of the test passed

	@return ETrue for a pass, EFalse for a fail

	 */

	virtual TBool Result();

	/**

	An accessor function for the object's TDmaTransferArgs

	*/

	const TDmaTransferArgs& TransferArgs() const

		{return iTransferArgs;}

	// The below methods are setters, which may be chained together

	// ie. The Named Parameter Idiom

	// @see http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.18

	inline CSingleTransferTest& UseNewRequest(TBool aFlag) {iUseNewRequest=aFlag; return *this;}

	inline CSingleTransferTest& UseNewFragment(TBool aFlag) {iUseNewFragment=aFlag; return *this;}

	inline CSingleTransferTest& UseNewDmaApi(TBool aFlag) {UseNewRequest(aFlag); UseNewFragment(aFlag); return *this;}

protected:

	virtual void OpenChannel();

	virtual void PreTransferSetup();

	virtual void CreateDmaRequest();

	virtual void Fragment();

	virtual void Queue();

	virtual void PostTransferCheck();

	virtual TInt DoPostTransferCheck();

	virtual void FreeRequest();

	virtual void CloseChannel();

protected:

	/**

	A handle to kernel side TDmaChannel object received after a channel is opened.

	*/

	TUint iChannelSessionCookie;

	/**

	A handle to kernel side DDmaRequest object.

	*/

	TUint iRequestSessionCookie;

	const TDmaTransferArgs& iTransferArgs;

	/**

	Expected transfer results

	*/

	TResultSet iExpected;

	/**

	Filled with actual transfer results

	*/

	TResultSet iActual;

	TBool iUseNewRequest; //!< If true then CSingleTransferTest will create a DDmaRequest with the v2 ctor

	TBool iUseNewFragment; //!< If true then CSingleTransferTest will use v2 Fragment API

	const TUint iMaxFragmentSize;

	};

/**

This class will be used for testing DMA Close() and Open() API

Extends CDmaTest by implemeting a RunTest() with a sequence of operations 

to test Close() and Open() API 

*/

class COpenCloseTest : public CDmaTest 

	{

public:

	COpenCloseTest(

			const TDesC& aName, TInt aIterations,	

			const MPostTransferCheck* aPostTferChk = NULL,

			const MPreTransfer* aPreTfer = NULL

			)

		: CDmaTest(aName, aIterations, aPreTfer, aPostTferChk), iOpenCloseResult(EFalse) , iRunOpen(EFalse)

		{}

	~COpenCloseTest();

	virtual void RunTest();