Stopwatches

A stopwatch measures time intervals using a high resolution timestamp counter. A stopwatch uses the KERNEL_Timestamp() call to acquire timing information whenever the watch is started or stopped. The accuracy and maximum interval that a stopwatch can measure depends upon the platform-specific implementation of the KERNEL_Timestamp() functionality.

Use CFG_TSTICKSPERSECOND in kernel_cfg.h to determine the resolution and maximum measurable interval for a stopwatch. For example, if CFG_TSTICKSPERSECOND is set to 100,000,000 (100Mhz); the stopwatch would have a resolution of 0.010 microseconds, and if stored as a 32-bit counter, it would be limited to measuring intervals less than ~42.949 seconds (2^32 / 100Mhz).

Basic Usage

#include "Kernel/kernel_stopwatch.h"

void APP_Example(void)
{
    STOPWATCH watch;
    STATUS status;
    UINT32 elapsed;


    STOPWATCH_Create(&watch, OPT_NONE);     /* Create and initialize a stopwatch */
    STOPWATCH_Start(&watch);                /* Start measuring the time */

    APP_DoWork();                           /* Do some work */

    elapsed = STOPWATCH_Elapsed(&watch);    /* Get total time (in ticks) that has elapsed */

    printf("%d ticks\n", elapsed);          /* Display the elapsed time */
}

API Reference

void STOPWATCH_Create(STOPWATCH* sw, UINT32 opt)
Creates and initializes a stopwatch.
PARAMETERS
sw A pointer to a caller allocated stopwatch to be initialized.
opt Additional options applied when the stopwatch is being created.
OPT_NONE No additional options.
OPT_START Indicates to start the stopwatch after creation.
RETURNS
None.
void STOPWATCH_Start(STOPWATCH* sw)
Starts a stopwatch.
PARAMETERS
sw A pointer to the stopwatch to be started.
RETURNS
None.
void STOPWATCH_Stop(STOPWATCH* sw)
Stops a stopwatch.
PARAMETERS
sw A pointer to the stopwatch to be stopped.
RETURNS
None.
void STOPWATCH_Reset(STOPWATCH* sw)
Resets a stopwatch.
PARAMETERS
sw A pointer to the stopwatch to be reset.
RETURNS
None.
void STOPWATCH_Restart(STOPWATCH* sw)
Resets and starts a stopwatch.
PARAMETERS
sw A pointer to the stopwatch to be restarted.
RETURNS
None.
BOOLEAN STOPWATCH_IsRunning(STOPWATCH* sw)
Returns an indication of whether a stopwatch is currently running.
PARAMETERS
sw A pointer to the target stopwatch.
RETURNS
TRUE if the stopwatch is currently running; otherwise FALSE.
UINT32 STOPWATCH_Elapsed(STOPWATCH* sw)
Calculates and returns the amount of time, in timestamp ticks, that has elapsed while the stopwatch has been running.
PARAMETERS
sw A pointer to the target stopwatch.
RETURNS
The total number of timestamp ticks that have elapsed while the stopwatch has been running.