1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
/*************************************************************************
* Copyright (C) 2008 Tavian Barnes <tavianator@gmail.com> *
* *
* This file is part of The Sandglass Library. *
* *
* The Sandglass Library is free software; you can redistribute it *
* and/or modify it under the terms of the GNU Lesser General Public *
* License as published by the Free Software Foundation; either version *
* 3 of the License, or (at your option) any later version. *
* *
* The Sandglass Library is distributed in the hope that it will be *
* useful, but WITHOUT ANY WARRANTY; without even the implied warranty *
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
* Lesser General Public License for more details. *
* *
* You should have received a copy of the GNU Lesser General Public *
* License along with this program. If not, see *
* <http://www.gnu.org/licenses/>. *
*************************************************************************/
/*
* libsandglass - a library for extremely high-resolution timing, benchmarking,
* and profiling.
*/
#ifndef SANDGLASS_H_INCLUDED
#define SANDGLASS_H_INCLUDED
#ifdef __cplusplus
/* We've been included from a C++ file; mark everything here as extern "C" */
extern "C" {
#endif
/* A type to represent a clock's time measurement attributes */
enum sandglass_incrementation_t
{
/*
* A clock which only increments during the current process's execution. Less
* precise than a monotonic clock, but more accurate and useful for profiling
* longer operations.
*/
SANDGLASS_INTROSPECTIVE,
/*
* A clock which increments in real-time, regardless of whether the current
* process was executing during that time or not. Allows for greater timing
* resolution, but will be inaccurate if the process is context-switched
* while being timed.
*/
SANDGLASS_MONOTONIC
};
typedef enum sandglass_incrementation_t sandglass_incrementation_t;
/* A type to represent a clock's timing resolution */
enum sandglass_resolution_t
{
/*
* Rely on the kernel to provide time information; less precise, more
* portable. Uses times().
*/
SANDGLASS_SYSTEM,
/*
* Get timing information directly from the processor; more precise, less
* portable. Uses the CLOCK_THREAD_CPUTIME_ID clock for
* SANDGLASS_INTROSPECTIVE mode, and the raw TSC for SANDGLASS_MONOTONIC.
*/
SANDGLASS_CPUTIME,
/*
* Get timing information accurate to within one CPU clock cycle - requires
* some looping and other trickery to account for TSCs which are not accurate
* to within one clock cycle. Not valid with SANDGLASS_INTROSPECTIVE.
*/
SANDGLASS_REALTICKS
};
typedef enum sandglass_resolution_t sandglass_resolution_t;
/* Attributes of a clock */
struct sandglass_attributes_t
{
sandglass_incrementation_t incrementation;
sandglass_resolution_t resolution;
};
typedef struct sandglass_attributes_t sandglass_attributes_t
struct sandglass_t
{
/* The attributes of the clock */
sandglass_attributes_t attributes;
/* Units of time which have passed */
long grains;
/* grains/resolution should give elapsed time in seconds */
long resolution;
/*
* Internal fields
*/
/* For SANDGLASS_TICKS looping support */
unsigned int i, loops;
};
typedef struct sandglass_t sandglass_t;
/*
* Creates a timer with at least the precision of `min', and at most the
* precision of `max'. Precisions are compared first by incrementation type:
* all monotonic timers are considered more precise than introspective timers.
* Then, higher resolution timers take precidence.
*
* If `min' is NULL, it defaults to { SANDGLASS_INTROSPECTIVE,
* SANDGLASS_SYSTEM }.
*
* If `max' is NULL, it defaults to at least `min', but not less than
* { SANDGLASS_INTROSPECTIVE, SANDGLASS_CPUTIME }.
*/
int sandglass_create(sandglass_t *sandglass,
const sandglass_attributes_t *min,
const sandglass_attributes_t *max);
int sandglass_begin(sandglass_t *sandglass);
int sandglass_elapse(sandglass_t *sandglass);
/* Use this to prevent a loop from being unrolled */
#define SANDGLASS_NO_UNROLL() __asm__ __volatile__ ("")
/*
* Macro to facilitate correct benchmarking of blocks of code. May be called
* like so:
* sandglass_bench(&sandglass, f(x))
* or like so:
* sandglass_bench(&sandglass, {
* f(x);
* g(x);
* });
*/
#define sandglass_bench(sandglass, routine) \
do { \
routine; \
sandglass_begin(sandglass); \
for ((sandglass)->i = 0; (sandglass)->i < (sandglass)->loops; ++i) { \
SANDGLASS_NO_UNROLL(); \
routine; \
} \
sandglass_elapse(sandglass); \
} while (0)
/*
* Low-level API
*/
/* Read the time stamp counter */
long sandglass_get_tsc();
#ifdef __cplusplus
}
#endif
#endif /* SANDGLASS_H_INCLUDED */
|
