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
53extern "C" {
54#endif
55
56#include <mach/mach_time.h>
57
58
59typedef 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 */
71extern double CPUTimeDeltaSec(CPUTime from, CPUTime to);	// seconds
72extern double CPUTimeDeltaMs(CPUTime from, CPUTime to);		// milliseconds
73extern 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 */
80double CPUTimeAvg(
81	const double *array,
82	unsigned arraySize);
83
84#ifdef __cplusplus
85}
86#endif
87
88#endif	/* _CPUTIME_H_ */
89
90