// Copyright (c) 2002-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:

//

#if !defined(__BM_SUITE_H__)

#define __BM_SUITE_H__

#include <e32test.h>

#include "d32bm.h"

/**

 * Gets access to the benchmark suite global log window/file.

 */

extern RTest test;

/**

 * Tests for an error condition.

 *

 * If the error condition is detected the macro prints out the file name, the line number and 

 * the error code, and aborts the benchmark suite.  

 *

 * @param aError an error number; printed out in the case if the error condition is detected.

 * @param aCond non-error condition: if 1 - no errors; if 0 - error. 

 */

#define BM_ERROR(aError, aCond) \

	__ASSERT_ALWAYS(aCond, bm_error_detected((TInt) aError, "'"#aCond"'", __FILE__, __LINE__))

void bm_error_detected(TInt aError, char* aCond, char* aFile, TInt aLine);

/**

 * Verify a condition

 *

 * If the value of condition is 0 prints out the file name, the line number and 

 * aborts the benchmark suite.

 *

 * @param aCond the condition that shell be verified.

 */

#define BM_ASSERT(aCond) \

	__ASSERT_DEBUG(aCond, bm_assert_failed("'"#aCond"'", __FILE__, __LINE__))

void bm_assert_failed(char* aFile, char* aCond, TInt aLine);

/**

 * An object of <code>TBMResult</code> class collects results of a measurement of a single perfrormance characteristic.

 * 

 * Objects of <code>TBMResult</code> class are typically reside in benchmark programs' static data

 * and returned as programs' results.

 */

class TBMResult

	{

public:

	/**

	 * Constructs a non-initialized <code>TBMResult</code> object. 

	 * Such a non-intialised object must be reset using void <code>TBMResult::Reset(const TDesC&)</code> function 

	 * prior to be actually used.

	 */

	TBMResult()	{}

	/**

	 * Constructs a <code>TBMResult</code> object. 

	 *

	 * @param aName the measurement tite.

	 */

	TBMResult(const TDesC& aName); 

	/**

	 * Resets an existing <code>TBMResult</code> object. 

	 * Sets the object in exactly the same state as <code>TBMResult::TBMResult(const TDesC&)</code>.

	 *

	 * @param aName the measurement tite.

	 */ 

	void Reset(const TDesC& aName);

	/**

	 * Stores the result of a new iteration.

	 *

	 * @param aTicks the iteration's elapsed time in ticks.

	 */

	void Cumulate(TBMTicks aTicks);

	/**

	 * Stores the cumulated result of a number of iterations.

	 *

	 * @param aTicks the cumulated elapsed time

	 * @param aIter the number of iterations.

	 */

	void Cumulate(TBMTicks aTicks, TBMUInt64 aIter);

	/**

	 * Calculate <code>TBMResult::iMin, TBMResult::iMax, TBMResult::iAverage</code> in nano-seconds

	 */

	void Update();

	/**

	 * The title of the performance measurement

	 */

	TPtrC	iName;

	/**

	 * The number of iteration has been performed

	 */

	TBMUInt64	iIterations;

	/**

	 * The minimal elapsed time in nano-seconds.

	 */

	TBMNs	iMin;

	/**

	 * The maximal elapsed time in nano-seconds

	 */ 

	TBMNs	iMax;

	/**

	 * The average elapsed time in nano-seconds.

	 */

	TBMNs	iAverage;

	enum

		{ 	

		/**

		 * The size of the buffer for the results of leading iterations

		 */

		KHeadSize = 4

		};

	enum

		{

		/**

		 * The size of the buffer for the results of tailing iterations

		 */

		KTailSize = 4 

		};

	/**

	 * The buffer with the results of <code>KHeadSize</code> leading iterations.

	 */

	TBMNs	iHead[KHeadSize];

	/**

	 * The buffer with the results of <code>KTailSize</code> trailing iterations.

	 */

	TBMNs	iTail[KTailSize];

// private:

	void Reset();

	TBMTicks	iMinTicks;				// the minimal elapsed time in ticks

	TBMTicks	iMaxTicks;				// the maximal elapsed time in ticks

	TBMTicks	iCumulatedTicks;		// the elapsed time in ticks cumulated over iCumulatedIterations

	TBMUInt64	iCumulatedIterations;	// the number of iterations for iCumulatedTicks

	TBMTicks	iHeadTicks[KHeadSize];	// the first KHeadSize results in ticks

	TBMTicks	iTailTicks[KTailSize];	// the last KTailSize results in ticks

	};

/**

 * An object of <code>TBMTimeInterval</code> can be used to measure potentially very long time interval.

 * 

 * If the measured time interval is shorter than the period of <code>RBMTimer</code> 

 * this high-precision timer will be used; otherwise, <code>TTime</code> timer will be used.

 */

class TBMTimeInterval

	{

public:

	/**

	 * A static function to initialize the class static state. 

	 * Called once by the benchmark suite launcher.

	 */

	static void Init();

	/**

	 * Begins the time interval measurement.

	 */

	void Begin();

	/**

	 * Ends the time interval measurement.

	 *

	 * @return the elapsed time in nano-seconds

	 */

	TBMNs EndNs();

	/**

	 * Ends the time interval measurement.

	 *

	 * @return the elapsed time in <code>RBMTimer</code> ticks. 

	 *		Note that the time is always returned in <code>RBMTimer</code> ticks regardless which of two timers,

	 *		<code>TTime</code> or <code>RBMTimer</code>, was actually used.

	 */

	TBMTicks End();

	/**

	 * Period of RBMTimer in nano-seconds

	 */

	static TBMNs	iStampPeriodNs;

	/**

	 * Period of RBMTimer in ticks

	 */

	static TBMTicks	iStampPeriod;

private:

	TBMTicks	iStamp;				// the starting time in RBMTimer ticks

	TTime		iTime;				// the starting TTime

	};

/**

 * Calculates elapsed time in ticks taking care about possible timer overflow.

 *

 * @param aT0 the beginning of the measured interval

 * @param aT1 the end of the measured interval.

 * 

 */

inline TBMTicks TBMTicksDelta(TBMTicks aT0, TBMTicks aT1)

	{

	return (aT0 <= aT1) ? (aT1 - aT0) : TBMTimeInterval::iStampPeriod - (aT0 - aT1);

	}

/**

 * Absolute thread prioiries to be used by benchmark programs

 */

enum 

	{

	/**

	 * Absolute priority to be used for high-priority threads.

	 * 

	 */

	KBMPriorityHigh = 60, // 60 is above all DFC 26 is below timer DFC

	/**

	 * Absolute priority to be used for middle-priority threads.

	 * This is also the default prioirty - performance benchmarks are started at this prioirty.

	 */	

	KBMPriorityMid = KBMPriorityHigh - 1,

	/**

	 * Absolute priority to be used for low-priority threads.

	 */

	KBMPriorityLow = KBMPriorityMid - 1

	};

/**

 * An object of <code>TBMSpawnArgs</code> type is used to pass arguments through 

 * <code>BMProgram::SpawnChild()</code> function from a parent to a child thread.

 *

 * <code>TBMSpawnArgs</code> is typically used as the base class for the actual argument passing object 

 * which may define some additional benchmark program specific arguments. 

 * The command line descriptor is used to pass a copy of the whole <code>TBMSpawnArgs</code> object 

 * from the parent process to the child one.

 */

struct TBMSpawnArgs

	{

	/**

	 * A magic value to allow the child recognize a command line as a <code>TBMSpawnArgs</code> object.

	 * Intialized by constructor.

	 */

	TInt			iMagic;

	/**

	 * A handle to the parent thread. 

	 * Intialized by constructor.

	 */

	RThread			iParent;

	/**

	 * The id of the parent thread.

	 * Intialized by constructor.

	 */

	TThreadId		iParentId;

	/**

	 * If <code>ETrue</code> the child thread runs in a separate process; 

	 * otherwise, the child thread runs within the parent's process.

	 * Intialized by constructor.

	 */

	TBool			iRemote;

	/**

	 * The child entry point.

	 * Intialized by constructor.

	 */

	TThreadFunction iChildFunc;

	/**

	 * The child thread absolute prioirty.

	 * Intialized by constructor.

	 */

	TInt			iChildPrio;

	TInt			iChildOrigPriority;

	/**

	 * The actual size of the <code>TBMSpawnArgs</code> object.

	 * Intialized by constructor.

	 */

	TInt			iSize;

	/**

	 * The TBMSpawnArgs magic value.

	 */

	static const TInt KMagic;

	/**

	 * Construct a new <code>TBMSpawnArgs</code> object.

	 *

	 * @param aChildFunc the child entry point

	 * @param aChildPrio the child thread absolute prioirty

	 * @param aRemote if <code>ETrue</code> the child thread must be created in a separate process; 

	 *		otherwise, the child thread must be created within the parent's process.

	 */

	TBMSpawnArgs(TThreadFunction aChildFunc, TInt aChildPrio, TBool aRemote, TInt aSize);

	/**

	 * Releases all allocated resources e.g. (<code>iParent</code> handle)

	 */

	~TBMSpawnArgs();

	};

/**

 * Child thread interface. Returned by <code>BMProgram::SpawnChild()</code>

 */

class MBMChild

	{

public:

	/**

	 * Wait for the actual child thread termination.

	 */

	virtual void WaitChildExit() = 0;

	/**

	 * Requests the child thread termination.

	 */

	virtual void Kill() = 0;

	};

/**

 * A benchmark program is implemented as a sub-class of the abstract <code>BMProgram</code> class.

 * 

 * A typical benchmark program implements <code>BMProgram::Run()</code> pure virtual function and 

 * instantiate an object of the implemented sub-class in its static data.

 */

class BMProgram 

	{

private:

	BMProgram*	iNext;

	TPtrC		iName;

	MBMChild* SpawnLocalChild(TBMSpawnArgs*);

	MBMChild* SpawnRemoteChild(TBMSpawnArgs*);

public:

	/**

	 * Utility function to change a thread's absolute priority.

	 * 

	 * @param aThread a handle ro the target thread.

	 * @param aNewPrio a new absolute priority for the target thread

	 * @return the old absolute prioirty of the target thread 

	 */

	static TInt SetAbsPriority(RThread aThread, TInt aNewPrio);	

	/**

	 * Constructs a new <code>BMProgram</code> object.

	 *

	 * @param aName the bechmark program's title

	 */

	BMProgram(const TDesC& aName) : iName(aName)

		{}

	/**

	 * Gets the nest program in the banchmark suite

	 *

	 * @return a pointer to the <code>BMProgram</code> object corresponding to the next benchmark program

	 *		in the benchmark suite

	 */

	BMProgram*& Next()

		{

		return iNext;

		}

	/**

	 * Gets the benchmark program title

	 * 

	 * @return a refernce to the descriptor containing the benchmark program title.

	 */

	const TDesC& Name()

		{

		return iName;

		}

	/**

	 * Runs the benchmark program.

	 *

	 * @param aIter the required number of iterations

	 * @retval aCount the number of performance characteristics measured by the benchmark program.

	 * @return a pointer to an array of <code>TBMResult</code> objects with the results of measurements of

	 *		individual performance characteristics. The number of array's elements is returned as 

	 *		aCount argument.

	 */

	virtual TBMResult* Run(TBMUInt64 aIter, TInt* aCount) = 0;

	/**

	 * Spawn a child thread

	 * 

	 * @param args a pointer to a <code>TBMSpawnArgs</code> object that contains genric spawn operation parameters

	 *		as well as program specific arguments to be passed to the chile thread.

	 */

	MBMChild* SpawnChild(TBMSpawnArgs* args);

	/**

	 * The main benchmark thread's absolute priority as was assigned by the loader. 

	 */

	TInt	iOrigAbsPriority;

	};

/**

 * The benchmark suite wide handle to the high-precision <code>RBMTimer</code>.

 */

extern RBMTimer bmTimer;

extern BMProgram* bmSuite;

void AddrtLatency();

void AddOverhead();

void AddSync();

void AddIpc();

void AddThread();

void AddProperty();

#endif