SecurityTests/cspxutils/utilLib/cputime.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please
   7  * obtain a copy of the License at http://www.apple.com/publicsource and
   8  * read it before using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  12  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  13  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  14  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  15  * Please see the License for the specific language governing rights and
  16  * limitations under the License.
  17  */
  18
  19 /*
  20  * cputime.h - high resolution timing module
  21  *
  22  * This module uses a highly machine-dependent mechanism to get timestamps
  23  * directly from CPU registers, without the overhead of a system call. The
  24  * timestamps are exported as type CPUTime and you should not concern yourself
  25  * with exactly what that is.
  26  *
  27  * We provide routines to convert a difference between two CPUTimes as a double,
  28  * in seconds, milliseconds, and microseconds. Th
  29  *
  30  * The cost (time) of getting a timestamp (via CPUTimeRead()) generally takes
  31  * two or fewer times the resolution period, i.e., less than 80 ns on a 100 MHz
  32  * bus machine, often 40 ns.
  33  *
  34  * The general usage of this module is as follows:
  35  *
  36  * {
  37  *              set up test scenario;
  38  *              CPUTime startTime = CPUTimeRead();
  39  *              ...critical timed code here...
  40  *              CPUTime endTime = CPUTimeRead();
  41  *              double elapsedMilliseconds = CPUTimeDeltaMs(startTime, endTime);
  42  * }
  43  *
  44  * It's crucial to place the CPUTimeDelta*() call OUTSIDE of the critical timed
  45  * area. It's really cheap to snag the timestamps, but it's not at all cheap
  46  * to convert the difference between two timestamps to a double.
  47  */
  48
  49 #ifndef _CPUTIME_H_
  50 #define _CPUTIME_H_
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 #include <mach/mach_time.h>
  57
  58
  59 typedef uint64_t CPUTime;
  60
  61 /*
  62  * Obtain machine-dependent, high resolution, cheap-to-read timestamp.
  63  */
  64 #define CPUTimeRead() mach_absolute_time()
  65
  66 /*
  67  * Convert difference between two CPUTimes into various units.
  68  * Implemented as separate functions to preserve as much precision as possible
  69  * before required machine-dependent "divide by clock frequency".
  70  */
  71 extern double CPUTimeDeltaSec(CPUTime from, CPUTime to);        // seconds
  72 extern double CPUTimeDeltaMs(CPUTime from, CPUTime to);         // milliseconds
  73 extern double CPUTimeDeltaUs(CPUTime from, CPUTime to);         // microseconds
  74
  75 /*
  76  * Calculate the average of an array of doubles. The lowest and highest values
  77  * are discarded if there are more than two samples. Typically used to get an
  78  * average of a set of values returned from CPUTimeDelta*().
  79  */
  80 double CPUTimeAvg(
  81         const double *array,
  82         unsigned arraySize);
  83
  84 #ifdef __cplusplus
  85 }
  86 #endif
  87
  88 #endif  /* _CPUTIME_H_ */
  89