/* timexLib.c - execution timer facilities *//* Copyright 1984-2001 Wind River Systems, Inc. */#include "copyright_wrs.h"/*modification history--------------------03x,16oct01,jn   use symFindSymbol for symbol lookup (SPR #7453)03w,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).03v,14feb97,dvs  added error checking in timexShowCalls (SPR #6876).03v,14feb97,dvs  timexShowCalls now prints func addr if lookup in sym table 		 fails (SPR #6876).03u,05may93,caf  tweaked for ansi.03t,13feb93,kdl  changed cplusLib.h to private/cplusLibP.h (SPR #1917).03s,20jan93,jdi  documentation cleanup for 5.1.03r,01aug92,srh  added C++ demangling idiom to timexShowCalls03q,26may92,rrr  the tree shuffle03p,01dec91,gae  more ANSI cleanup.03o,04oct91,rrr  passed through the ansification filter                  -changed functions to ansi style		  -changed VOID to void		  -changed copyright notice03n,05apr91,jdi	 documentation -- removed header parens and x-ref numbers;		 doc review by dnw.03m,24mar91,jdi  documentation cleanup.03l,10aug90,dnw  added include of timexLib.h.03k,10aug90,kdl  added forward declarations for functions returning void.03j,10jul90,dnw  changed declaration of timexNull from void to int to allow		   void to be void one day03i,12mar90,jcf  symbol table type now SYM_TYPE.03h,07mar90,jdi  documentation cleanup.03g,03apr89,ecs  made optional arguments explicit in timexFunc, timex, timexN,	   +gae	    timexPost, timexPre.03f,20aug88,gae  documentation.03e,07jul88,jcf  lint.03d,05jun88,dnw  changed name to timexLib.03c,30may88,dnw  changed to v4 names.03b,01may88,gae  added null routine timLib().03a,27jan88,jcf  made kernel independent.02s,18nov87,ecs  documentation.02r,04nov87,ecs  documentation.02q,08jun87,llk  fixed initialization of tiPreCalls, tiTimeCalls, tiPostCalls.02p,23mar87,jlf  documentation.02o,12jan87,llk  corrected information in tihelp.02n,21dec86,dnw  changed to not get include files from default directories.02m,02dec86,llk  changed tiHelp to tihelp.02l,04sep86,jlf  documentation.02k,27jul86,llk  prints error messages to standard error (uses printErr)02j,05jun86,dnw  changed sstLib calls to symLib.02i,24mar86,dnw  de-linted.02h,19mar86,dnw  fixed calibration to include pushing of args and calling		   routine.		 corrected documentation.		 changed timeN to report how many reps it made.02g,11oct85,dnw  de-linted.02f,37aug85,rdc  changed MAX_SYM_LEN to MAX_SYS_SYM_LEN.02e,21jul85,jlf  documentation.02d,01jun85,rdc  updated documentation.02c,14aug84,jlf  changed calls to clkGetRate to sysClkGetRate.02b,16jul84,ecs  changed to use unix-style format codes.02a,24jun84,dnw  rewritten*//*This library contains routines for timing the execution of programs,individual functions, and groups of functions.  The VxWorks system clockis used as a time base.  Functions that have a short execution timerelative to this time base can be called repeatedly to establish anaverage 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- orpost-timing functions, to be executed before and after the timed functions.The routines timexPre() and timexPost() are used to specify the pre- andpost-timing functions, while timexFunc() specifies the functions tobe timed.The routine timex() is used to time a single execution of a function orgroup of functions.  If called with no arguments, timex() uses thefunctions in the lists created by calls to timexPre(), timexPost(), andtimexFunc().  If called with arguments, timex() times the functionspecified, instead of the previous list.  The routine timexN() works inthe same manner as timex() except that it iterates the function calls tobe timed.EXAMPLESThe routine timex() can be used to obtain the execution time of a singleroutine:.CS    -> timex myFunc, myArg1, myArg2, ....CEThe routine timexN() calls a function repeatedly until a 2% or bettertolerance is obtained:.CS    -> timexN myFunc, myArg1, myArg2, ....CEThe routines timexPre(), timexPost(), and timexFunc() are used to specifya list of functions to be executed as a group:.CS    -> 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, ....CEThe list is executed by calling timex() or timexN() without arguments:.CS    -> timex.ft 1or.ft P    -> timexN.CEIn this example, <myPreFunc1> and <myPreFunc2> are called with theirrespective arguments.  <myFunc1>, <myFunc2>, and <myFunc3> are thencalled in sequence and timed.  If timexN() was used, the sequence iscalled repeatedly until a 2% or better error tolerance is achieved.Finally, <myPostFunc> is called with its arguments.  The timing resultsare reported after all post-timing functions are called.NOTEThe timings measure the execution time of the routine body, without theusual subroutine entry and exit code (usually LINK, UNLINK, and RTSinstructions).  Also, the time required to set up the arguments andcall the routines is not included in the reported times.  This isbecause these timing routines automatically calibrate themselves bytiming the invocation of a null routine, and thereafter subtractingthat constant overhead.INCLUDE FILES: timexLib.hSEE ALSO: spyLib*/#include "vxWorks.h"#include "symLib.h"#include "stdio.h"#include "string.h"#include "sysSymTbl.h"#include "sysLib.h"#include "tickLib.h"#include "timexLib.h"#include "private/cplusLibP.h"#define MAX_CALLS	4		/* max functions in each category */#define MAX_ARGS	8		/* max args to each function */#define MAX_PERCENT	2		/* max percent error for auto-timing */#define MAX_REPS	20000		/* max reps for auto-timing */#define TIMEX_DEMANGLE_PRINT_LEN 256typedef struct			/* CALL */    {    VOIDFUNCPTR func;			/* function to call */    int arg [MAX_ARGS];			/* args to function */    } CALL;typedef CALL CALL_ARRAY [MAX_CALLS];LOCAL char *timexScaleText [] =    {    "secs",			/* scale = 0 */    "millisecs",		/* scale = 1 */    "microsecs",		/* scale = 2 */    };static void timexNull (void);		/* forward declaration */LOCAL CALL_ARRAY timexPreCalls =	/* calls to be made just before timing*/    {    { timexNull },    { timexNull },    { timexNull },    { timexNull },    };LOCAL CALL_ARRAY timexTimeCalls =	/* calls to be timed */    {    { timexNull },    { timexNull },    { timexNull },    { timexNull },    };LOCAL CALL_ARRAY timexPostCalls =	/* calls to be made just after timing */    {    { timexNull },    { timexNull },    { timexNull },    { timexNull },    };LOCAL CALL_ARRAY timexNullCalls =    {    { timexNull },    { timexNull },    { timexNull },    { timexNull },    };LOCAL int overhead;		/* usecs of overhead per rep in timing test *//* forward static functions */static void timexAddCall (CALL *callArray, int i, FUNCPTR func, int arg1, int		arg2, int arg3, int arg4, int arg5, int arg6, int arg7,		int arg8);static void timexAutoTime (CALL_ARRAY preCalls, CALL_ARRAY timeCalls,		CALL_ARRAY postCalls, int *pNreps, int *pScale, int *pTime,		int *pError, int *pPercent);static void timexCal (void);static void timexClrArrays (void);static void timexMakeCalls (CALL_ARRAY calls);static void timexScale (int ticks, int reps, int *pScale, int *pTime, int		*pError, int *pPercent);static void timexShowCalls (CALL_ARRAY calls);static void timexTime (int reps, CALL_ARRAY preCalls, CALL_ARRAY timeCalls,		CALL_ARRAY postCalls, int *pScale, int *pTime, int *pError,		int *pPercent);/********************************************************************************* timexInit - include the execution timer library** 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.** RETURNS: N/A*/void timexInit (void)    {    }/********************************************************************************* timexClear - clear the list of function calls to be timed** This routine clears the current list of functions to be timed.** RETURNS: N/A*/void timexClear (void)    {    timexClrArrays ();    timexShow ();    }/********************************************************************************* timexFunc - specify functions to be timed** 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>.** RETURNS: N/A** SEE ALSO: timex(), timexN()*/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    )    {    timexAddCall (timexTimeCalls, i, func, arg1, arg2, arg3, arg4, arg5, arg6,		  arg7, arg8);    timexShow ();    }/********************************************************************************* timexHelp - display synopsis of execution timer facilities** This routine displays the following summary of the available* execution timer functions:* .CS*     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.* .CE** RETURNS: N/A*/void timexHelp (void)    {    static char *helpMsg [] =    {    "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.\n",    "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.",    NULL,	/* list terminator */    };    FAST char **ppMsg;    printf ("\n");    for (ppMsg = helpMsg; *ppMsg != NULL; ++ppMsg)	printf ("%s\n", *ppMsg);    }/********************************************************************************* timex - time a single execution of a function or functions** 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().** RETURNS: N/A** SEE ALSO: timexFunc(), timexPre(), timexPost(), timexN()*/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    )    {    int scale;    int time;    int error;    int percent;    /* if function specified, clear any existing functions and add this one */    if (func != NULL)	{	timexClrArrays ();	timexAddCall (timexTimeCalls, 0, func, arg1, arg2, arg3, arg4, arg5,		      arg6, arg7, arg8);	}    /* calibrate if necessary */    if (overhead == 0)	timexCal ();    /* time calls */    timexTime (1, timexPreCalls, timexTimeCalls, timexPostCalls,	    &scale, &time, &error, &percent);    if (percent > 50)	{	printErr (	    "timex: execution time too short to be measured meaningfully\n");	printErr ("       in a single execution.\n");	printErr ("       Type \"timexN\" to time repeated execution.\n");	printErr ("       Type \"timexHelp\" for more information.\n");	}    else	printErr ("timex: time of execution = %d +/- %d (%d%%) %s\n",		  time, error, percent, timexScaleText [scale]);    }/********************************************************************************* timexN - time repeated executions of a function or group of functions** 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.)** RETURNS: N/A** SEE ALSO: timexFunc(), timex()*/