OAL Timer GetTickCount Tests (Compact 2013)
3/26/2014
The OAL Timer GetTickCount Tests verify the behavior of the system timer queried through the GetTickCount() API.
The tests check the system timer resolution, verify that the clock does not tick backwards, and query and print out the current tick count sample.
Test cases 1020, 1030, and 1050 take 30 minutes each to execute (with the provided command line parameters). Therefore this suite can take in excess of 1.5 hours to run.
Test Prerequisites
Your device must meet the following requirements before you run this test.
The test should be run on a minimal OS design, such as one with only the following SYSGENs set to minimize the likelihood of interactions from other system components:
- SYSGEN_NETWORKING=1
- SYSGEN_SHELL=1
The following table shows the hardware requirements for the tests.
Requirement |
Description |
|---|---|
GetTickCount Clock |
Clock that corresponds to the GetTickCount function |
The following table shows the software requirements for the tests.
Requirements |
Description |
|---|---|
Tux.exe |
Tux test harness, required for executing the test |
Kato.dll |
Kato logging engine, required for logging test data |
OalTestTimers.dll |
Library that contains the timer tests |
Subtests
The following table lists the subtests included in this test.
SubTest ID |
Description |
|---|---|
1010 |
Tick Count Resolution (high priority): Determines the resolution of the clock for the GetTickCount function. The test case records the resolution of the clock for 1000 iterations, and then averages the recorded values to report a result. This test case runs at a scheduler priority of 1. This test case prints out the calculated resolution; the user must verify that it is as expected. The test case fails if the average of the recorded values is greater than the maximum specified resolution, which is 1 millisecond (ms) by default. You can specify the maximum resolution by specifying -c "-gtcMaxRes seconds", where seconds is the maximum number of seconds for resolution. This parameter accepts decimal values to a resolution of 1 ms; for example, -gtcMaxRes 0.001 specifies 1 ms. Note: This test case evaluates resolution, not precision. The precision of a clock is the smallest unit of measurement that the clock displays. The resolution is the smallest interval/tick that the clock accurately measures. |
1020 |
Tick Count Backwards Check - busy sleep: Confirms that the clock for GetTickCount is a monotonically increasing value that runs backward only when it overflows. This test case reads each subsequent clock tick and verifies that the value is greater than the previous value. If the value is less than the previous value, the difference between the values must be less than twice the resolution of the clock. If the difference between the values is greater than twice the resolution of the clock, this test case fails. By default, this test case runs for three hours. You can specify the length of time that it runs by specifying -c "-backwardsRunTime seconds", where seconds is the run time for the test in seconds. The timer for GetTickCount wraps once approximately every 49 days. To test the condition where the timer overflows, set the timer to wrap soon. The test must run a quick calibration to determine how many iterations are needed to run for the full test time. The default length of the calibration test is 10 seconds, but the length of the calibration test can be changed with the -CalibThresh <time in ms> option on the command line. |
1030 |
Tick Count Backwards Check - random sleep: This test confirms that the clock for the GetTickCount function is a monotonically increasing value that runs backward only when it overflows. This test case does the same thing as test case 1020 except that it sleeps for random time intervals (between 0 and 1000 ms) between subsequent calls to GetTickCount(). That is, the test checks the timer every time it wakes up after sleeping for a random amount of time. By default, this test case runs for three hours. As in the case of test case 1020, you can specify the length of time the test runs by specifying -c "-backwardsRunTime seconds", where seconds is the run time for the test in seconds. You can also specify the time used in calibration via the -c "-CalibThresh" command line parameter. |
1050 |
Print GetTickCount: Prints out the value of GetTickCount ten times, sleeping for one second between each call. |
Setting Up the Test
This test has no additional requirements beyond the standard test environment setup.
Running the Test
The OAL Timer GetTickCount Test executes the 'tux -o -d OalTestTimers.dll -x 1000-1050 -c"-backwardsRunTime 1800"' command on default execution.
You can modify the OAL Timer GetTickCount Tests by editing the command line for the test. To specify the following optional command line parameter for this test, use the -c command line parameter, which causes Tux to pass the specified string into the test module. For more information about how to edit the command line for a test, see Editing the Command-Line for a Test.
The following table shows the optional command-line parameter used by the Tick Count Resolution (1010) subtest.
Command-line parameter |
Description |
|---|---|
-gtcMaxRes <seconds> |
Specifies the maximum resolution in seconds allowed for the GTC timer. It accepts integer or decimal values; for example, -gtcMaxRes 0.001 specifies 1 ms. The resolution must be a multiple of 1 ms (0.001 second). The default value is 0.001 s (1 ms). |
The following table shows the optional command-line parameters used by the GTC Backwards Check with Busy Sleep (1020) and Random Sleep (1030) subtests.
Command-line parameter |
Description |
|---|---|
-backwardsRunTime <seconds> |
Specifies the run time for the test, in seconds. The default run time is three hours. |
-CalibThresh <time in ms> |
Amount of time allowed for calibration, in milliseconds. The default time is 10 seconds. |
Verifying the Test
When the test completes, verify that "PASS" appears in the test log for all subtests.
Troubleshooting the Test
- Ensure that you are running on a minimal OS configuration.
- Ensure that drivers and servers running on the OS meet real-time constraints and do not interrupt the test.
- Verify that no drivers are running at overly high priority or for overly long time periods.
- The Kernel Scheduler (ksched) test may be helpful for further investigation of failures.
- Determine the point of failure and record the exact error message. Check that the setup steps were followed and that all prerequisites were met. If the source code is available, examine the point of failure in code to see if any additional information can be gathered about the failure domain.