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

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Eclipse Public License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.eclipse.org/legal/epl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 //

    15 

    16 #if !defined(__BM_BM_LDD_H__)

    17 #define __BM_BM_LDD_H__

    18 

    19 #include <e32def.h>

    20 #include <e32cmn.h>

    21 

    22 /**

    23  * The filename of the benchmark-suite logical device driver DLL

    24  */

    25 _LIT(KBMLddFileName, "bm_ldd");

    26 /**

    27  * The name of the benchmark-suite logical device.

    28  */

    29 _LIT(KBMLdName, "bm_dev");

    30 

    31 /**

    32  * The filename of the benchmark-suite physical device driver DLL

    33  */

    34 _LIT(KBMPddFileName, "bm_pdd");

    35 /**

    36  * The name of the benchmark-suite physical device.

    37  */

    38 _LIT(KBMPdName, "bm_dev.pdd");

    39 

    40 typedef Uint64 TBMUInt64;

    41 typedef Int64 TBMInt64;

    42 

    43 /**

    44  * Integer type for high-resolution RBMTimer ticks.

    45  */

    46 typedef TBMUInt64 TBMTicks;

    47 /**

    48  * Integer type for nano-second

    49  */

    50 typedef TBMUInt64 TBMNs;

    51 

    52 /**

    53  * Translates seconds to nano-seconds

    54  */

    55  inline TBMNs BMSecondsToNs(TInt aSeconds)

    56 	{

    57 	return TBMNs(aSeconds) * 1000 * 1000 * 1000;

    58 	}

    59 /**

    60  * Translates milliseconds to nanoseconds

    61  */

    62  inline TBMNs BMMsToNs(TInt aMs)

    63 	{

    64 	return TBMNs(aMs) * 1000 * 1000;

    65 	}

    66 /**

    67  * Translates microseconds to nanoseconds

    68  */

    69  inline TBMNs BMUsToNs(TBMUInt64 aUs)

    70 	{

    71 	return TBMNs(aUs) * 1000;

    72 	}

    73 /**

    74  * Translates nanoseconds to seconds

    75  */

    76 inline TInt BMNsToSeconds(TBMNs aNs)

    77 	{

    78 	return TInt(aNs/(1000 * 1000 * 1000));

    79 	}

    80 /**

    81  * Translates nanoseconds to milliseconds

    82  */

    83 inline TInt BMNsToMs(TBMNs aNs)

    84 	{

    85 	return TInt(aNs/(1000 * 1000));

    86 	}

    87 /**

    88  * Translates nanoseconds to microseconds

    89  */

    90 inline TBMUInt64 BMNsToUs(TBMNs aNs)

    91 	{

    92 	return aNs/(1000);

    93 	}

    94 

    95 /**

    96  * RBMChannel class defines the user-side API to the kernel-side half of the benchmark-suite.

    97  *

    98  * The kernel-side half is implmented as <code>KBMLdName</code> logical and <code>KBMPdName</code> physical 

    99  * devices by <code>KBMLddFileName</code> logical and <code>KBMPddFileName</code> physical device driver DLLs

   100  * respectively.

   101  *

   102  * The API enables to measure some kernel-side performace parameters such as interrupt and preemption latences. 

   103  */

   104 class RBMChannel : public RBusLogicalChannel

   105 	{

   106 public:

   107 	

   108 	/**

   109 	 * Measured performace parameters.

   110 	 */

   111 	enum TMode

   112 		{

   113 		/**

   114 		 * Interrupt Latency is the elapsed time from the occurrence of an external event to the execution of 

   115 		 * the first instruction of the corresponding interrupt service routine (ISR).

   116 		 */

   117 		EInterruptLatency,

   118 		/**

   119 		 * Kernel Preemption Latency is the elapsed time from the end of the ISR to the execution of the first

   120 		 * instruction of a kernel thread activated by the ISR.

   121 		 */

   122 		EKernelPreemptionLatency,

   123 		/**

   124 		 * User Preemption Latency is the elapsed time from the end of the ISR to the execution of the first 

   125 		 * instruction of a user thread activated by the ISR

   126 		 */

   127 		EUserPreemptionLatency,

   128 		/**

   129 		 * NTimer callback invocations' jitter. 

   130 		 */

   131 		ENTimerJitter,

   132 		/**

   133 		 * The kernel-side overhead of one high-precision timer read.

   134 		 */

   135 		ETimerStampOverhead

   136 		};

   137 

   138 	/**

   139 	 * The benchmark-suite logical device controls.

   140 	 * 

   141 	 * There is three groups of controls: (1) measurement of a performance parameter which is accessible through

   142 	 * RBMChannel, (2) high-resolution timer interface which is accessible through RBMTimer and (3) misc controls

   143 	 * accessible through RBMDriver.

   144 	 */

   145 	enum TControl

   146 		{

   147 		/**

   148 		 * Prepare to perform a sequence of measurements of a specific performance parameter.

   149 		 */

   150 		EStart,

   151 		/**

   152 		 * Perform one measurement.

   153 		 */

   154 		ERequestInterrupt,

   155 		/**

   156 		 * Get the result of the last measurement.

   157 		 */

   158 		EResult,

   159 

   160 		/**

   161 		 * Get the current high-resolution time.

   162 		 */

   163 		ETimerStamp,

   164 		/**

   165 		 * Get the high-resolution timer period.

   166 		 */		

   167 		ETimerPeriod,

   168 		/**

   169 		 * Translate a time value from high-resolution timer ticks to nanoseconds.

   170 		 */	

   171 		ETimerTicksToNs,

   172 		/**

   173 		 * Translate a time value from nanoseconds to high-resolution timer ticks.

   174 		 */

   175 		ETimerNsToTicks,

   176 

   177 		/**

   178 		 * Change the absolute priority of a thread.

   179 		 */

   180 		ESetAbsPriority

   181 		};

   182 

   183 #ifndef __KERNEL_MODE__

   184 	/**

   185 	 * Open the channel for measurements of one specific performance parameter.

   186 	 * 

   187 	 * @param aMode specifies the performance parameter.

   188 	 *

   189 	 * @return <code>KErrNone</code> on success; otherwise an error code.

   190 	 */

   191 	TInt Open(TMode aMode)

   192 		{

   193 		TInt r = DoCreate(KBMLdName, TVersion(1,0,1), KNullUnit, &KBMPdName, NULL);

   194 		if (r == KErrNone)

   195 			{

   196 			r = DoControl(EStart, (TAny*) aMode);

   197 			if (r != KErrNone)

   198 				{

   199 				Close();

   200 				}

   201 			}

   202 		return r;

   203 		}

   204 	/**

   205 	 * Perform one measurement.

   206 	 */

   207 	void RequestInterrupt()

   208 		{ 

   209 		DoControl(ERequestInterrupt); 

   210 		}

   211 	/**

   212 	 * Get the result of the last measurement.

   213 	 * 

   214 	 * @retval aTicks the result of the last measurement in RBMTimer's ticks

   215 	 */

   216 	void Result(TBMTicks* aTicks)

   217 		{

   218 		User::WaitForAnyRequest();

   219 		DoControl(EResult, aTicks); 

   220 		}

   221 #endif	

   222 	};

   223 

   224 /**

   225  * RBMDriver class defines the user-side API to kernel-side utility operations.

   226  *

   227  * The operations are implmented as <code>KBMLdName</code> logical device by <code>KBMLddFileName</code>

   228  * logical device driver DLL.

   229  *

   230  * The API enables to change the absolute prioirty of a thread. 

   231  */

   232 class RBMDriver : public RBusLogicalChannel

   233 	{

   234 public:

   235 #ifndef __KERNEL_MODE__

   236 	/**

   237 	 * Opens the channel

   238 	 *

   239 	 * @return <code>KErrNone</code> on success; otherwise an error code

   240 	 */

   241 	TInt Open()

   242 		{

   243 		return DoCreate(KBMLdName, TVersion(1,0,1), KNullUnit, &KBMPdName, NULL);

   244 		}

   245 	/**

   246 	 * Change the absolute prioirty of a thread.

   247 	 *

   248 	 * @param aThread a handle to the target thread

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

   250 	 *

   251 	 * @retval aOldPrio the old absolute priority of the target thread

   252 	 *

   253 	 * @return <code>KErrNone</code> on success; otherwise an error code

   254 	 */	

   255 	TInt SetAbsPriority(RThread aThread, TInt aNewPrio, TInt* aOldPrio)

   256 		{

   257 		TInt aPrio = aNewPrio;

   258 		TInt r = DoControl(RBMChannel::ESetAbsPriority, (TAny*) aThread.Handle(), (TAny*) &aPrio);

   259 		if (r == KErrNone)

   260 			{

   261 			*aOldPrio = aPrio;

   262 			}

   263 		return r;

   264 		}

   265 #endif

   266 	};

   267 

   268 /**

   269  * RBMTimer class defines the user-side API to the high-precision timer.

   270  *

   271  * The timer is implmented as <code>KBMLdName</code> logical and <code>KBMPdName</code> physical 

   272  * devices by <code>KBMLddFileName</code> logical and <code>KBMPddFileName</code> physical device driver DLLs

   273  * respectively.

   274  */

   275 class RBMTimer : public RBusLogicalChannel

   276 	{

   277 public:

   278 

   279 #ifndef __KERNEL_MODE__

   280 	/**

   281 	 * Opens the channel to the high-precision timer.

   282 	 *

   283 	 * @return <code>KErrNone</code> on success; otherwise an error code

   284 	 */

   285 	TInt Open()

   286 		{

   287 		return DoCreate(KBMLdName, TVersion(1,0,1), KNullUnit, &KBMPdName, NULL); 

   288 		}

   289 	/**

   290 	 * Gets the current time in ticks.

   291 	 *

   292 	 * @retval aTicks the current time in <code>TBMTicks</code>

   293 	 */

   294 	void Stamp(TBMTicks* aTicks)

   295 		{ 

   296 		DoControl(RBMChannel::ETimerStamp, aTicks); 

   297 		}

   298 	/**

   299 	 * Gets the timer period in ticks.

   300 	 *

   301 	 * @retval aPriod the timer period in <code>TBMTicks</code>

   302 	 */	

   303 	void Period(TBMTicks* aPeriod)

   304 		{ 

   305 		DoControl(RBMChannel::ETimerPeriod, aPeriod); 

   306 		}

   307 	/**

   308 	 * Translates ticks to nano-seconds.

   309 	 *

   310 	 * @param aTciks a pointer to the <code>TBMTicks</code> value to be translated.

   311 	 *

   312 	 * @retval aNs the resulting time value in nanoseconds.

   313 	 */	

   314 	void TicksToNs(TBMTicks* aTicks, TBMNs* aNs)

   315 		{ 

   316 		DoControl(RBMChannel::ETimerTicksToNs, aTicks, aNs); 

   317 		}

   318 	/**

   319 	 * Translates nanoseconds to ticks.

   320 	 *

   321 	 * @param aNs a pointer to the time value in nanoseconds to be translated.

   322 	 *

   323 	 * @retval aTicks the resulting time in <code>TBMTicks</code>.

   324 	 */		

   325 	void NsToTicks(TBMNs* aNs, TBMTicks* aTicks)

   326 		{ 

   327 		DoControl(RBMChannel::ETimerTicksToNs, aNs, aTicks); 

   328 		}

   329 #endif

   330 	};

   331 	

   332 #endif