VxWorks Reference Manual : Libraries
timexLib - execution timer facilities
timexInit( ) - include the execution timer library
timexClear( ) - clear the list of function calls to be timed
timexFunc( ) - specify functions to be timed
timexHelp( ) - display synopsis of execution timer facilities
timex( ) - time a single execution of a function or functions
timexN( ) - time repeated executions of a function or group of functions
timexPost( ) - specify functions to be called after timing
timexPre( ) - specify functions to be called prior to timing
timexShow( ) - display the list of function calls to be timed
This library contains routines for timing the execution of programs, individual functions, and groups of functions. The VxWorks system clock is used as a time base. Functions that have a short execution time relative to this time base can be called repeatedly to establish an average execution time with an acceptable percentage of error.
Up to four functions can be specified to be timed as a group. Additionally, sets of up to four functions can be specified as pre- or post-timing functions, to be executed before and after the timed functions. The routines timexPre( ) and timexPost( ) are used to specify the pre- and post-timing functions, while timexFunc( ) specifies the functions to be timed.
The routine timex( ) is used to time a single execution of a function or group of functions. If called with no arguments, timex( ) uses the functions in the lists created by calls to timexPre( ), timexPost( ), and timexFunc( ). If called with arguments, timex( ) times the function specified, instead of the previous list. The routine timexN( ) works in the same manner as timex( ) except that it iterates the function calls to be timed.
The routine timex( ) can be used to obtain the execution time of a single routine:
-> timex myFunc, myArg1, myArg2, ...The routine timexN( ) calls a function repeatedly until a 2% or better tolerance is obtained:-> timexN myFunc, myArg1, myArg2, ...The routines timexPre( ), timexPost( ), and timexFunc( ) are used to specify a list of functions to be executed as a group:-> timexPre 0, myPreFunc1, preArg1, preArg2, ... -> timexPre 1, myPreFunc2, preArg1, preArg2, ... -> timexFunc 0, myFunc1, myArg1, myArg2, ... -> timexFunc 1, myFunc2, myArg1, myArg2, ... -> timexFunc 2, myFunc3, myArg1, myArg2, ... -> timexPost 0, myPostFunc, postArg1, postArg2, ...The list is executed by calling timex( ) or timexN( ) without arguments:-> timex or -> timexNIn this example, myPreFunc1 and myPreFunc2 are called with their respective arguments. myFunc1, myFunc2, and myFunc3 are then called in sequence and timed. If timexN( ) was used, the sequence is called repeatedly until a 2% or better error tolerance is achieved. Finally, myPostFunc is called with its arguments. The timing results are reported after all post-timing functions are called.
The timings measure the execution time of the routine body, without the usual subroutine entry and exit code (usually LINK, UNLINK, and RTS instructions). Also, the time required to set up the arguments and call the routines is not included in the reported times. This is because these timing routines automatically calibrate themselves by timing the invocation of a null routine, and thereafter subtracting that constant overhead.
timexLib.h
timexInit( ) - include the execution timer library
void timexInit (void)
This null routine is provided so that timexLib can be linked into the system. If the configuration macro INCLUDE_TIMEX is defined, it is called by the root task, usrRoot( ), in usrConfig.c.
N/A
timexClear( ) - clear the list of function calls to be timed
void timexClear (void)
This routine clears the current list of functions to be timed.
N/A
timexFunc( ) - specify functions to be timed
void timexFunc ( int i, /* function number in list (0..3) */ FUNCPTR func, /* function to be added (NULL if to be deleted) */ int arg1, /* first of up to 8 args to call function with */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8 )
This routine adds or deletes functions in the list of functions to be timed as a group by calls to timex( ) or timexN( ). Up to four functions can be included in the list. The argument i specifies the function's position in the sequence of execution (0, 1, 2, or 3). A function is deleted by specifying its sequence number i and NULL for the function argument func.
N/A
timexHelp( ) - display synopsis of execution timer facilities
void timexHelp (void)
This routine displays the following summary of the available execution timer functions:
timexHelp Print this list. timex [func,[args...]] Time a single execution. timexN [func,[args...]] Time repeated executions. timexClear Clear all functions. timexFunc i,func,[args...] Add timed function number i (0,1,2,3). timexPre i,func,[args...] Add pre-timing function number i. timexPost i,func,[args...] Add post-timing function number i. timexShow Show all functions to be called. Notes: 1) timexN() will repeat calls enough times to get timing accuracy to approximately 2%. 2) A single function can be specified with timex() and timexN(); or, multiple functions can be pre-set with timexFunc(). 3) Up to 4 functions can be pre-set with timexFunc(), timexPre(), and timexPost(), i.e., i in the range 0 - 3. 4) timexPre() and timexPost() allow locking/unlocking, or raising/lowering priority before/after timing.
N/A
timex( ) - time a single execution of a function or functions
void timex ( FUNCPTR func, /* function to time (optional) */ int arg1, /* first of up to 8 args to call function with (optional) */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8 )
This routine times a single execution of a specified function with up to eight of the function's arguments. If no function is specified, it times the execution of the current list of functions to be timed, which is created using timexFunc( ), timexPre( ), and timexPost( ). If timex( ) is executed with a function argument, the entire current list is replaced with the single specified function.
When execution is complete, timex( ) displays the execution time. If the execution was so fast relative to the clock rate that the time is meaningless (error > 50%), a warning message is printed instead. In such cases, use timexN( ).
N/A
timexLib, timexFunc( ), timexPre( ), timexPost( ), timexN( )
timexN( ) - time repeated executions of a function or group of functions
void timexN ( FUNCPTR func, /* function to time (optional) */ int arg1, /* first of up to 8 args to call function with */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8 )
This routine times the execution of the current list of functions to be timed in the same manner as timex( ); however, the list of functions is called a variable number of times until sufficient resolution is achieved to establish the time with an error less than 2%. (Since each iteration of the list may be measured to a resolution of +/- 1 clock tick, repetitive timings decrease this error to 1/N ticks, where N is the number of repetitions.)
N/A
timexLib, timexFunc( ), timex( )
timexPost( ) - specify functions to be called after timing
void timexPost ( int i, /* function number in list (0..3) */ FUNCPTR func, /* function to be added (NULL if to be deleted) */ int arg1, /* first of up to 8 args to call function with */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8 )
This routine adds or deletes functions in the list of functions to be called immediately following the timed functions. A maximum of four functions may be included. Up to eight arguments may be passed to each function.
N/A
timexPre( ) - specify functions to be called prior to timing
void timexPre ( int i, /* function number in list (0..3) */ FUNCPTR func, /* function to be added (NULL if to be deleted) */ int arg1, /* first of up to 8 args to call function with */ int arg2, int arg3, int arg4, int arg5, int arg6, int arg7, int arg8 )
This routine adds or deletes functions in the list of functions to be called immediately prior to the timed functions. A maximum of four functions may be included. Up to eight arguments may be passed to each function.
N/A
timexShow( ) - display the list of function calls to be timed
void timexShow (void)
This routine displays the current list of function calls to be timed. These lists are created by calls to timexPre( ), timexFunc( ), and timexPost( ).
N/A