← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/virtualbox-ose/gutsy

« back to all changes in this revision

Viewing changes to include/iprt/timer.h

  • Committer: Bazaar Package Importer
  • Author(s): Steve Kowalik
  • Date: 2007-09-08 16:44:58 UTC
  • Revision ID: james.westby@ubuntu.com-20070908164458-wao29470vqtr8ksy
Tags: upstream-1.5.0-dfsg2
Import upstream version 1.5.0-dfsg2

Show diffs side-by-side

added added

removed removed

Lines of Context:
include/iprt/timer.h
 
1
/** @file
 
2
 * innotek Portable Runtime - Timer.
 
3
 */
 
4
 
 
5
/*
 
6
 * Copyright (C) 2006-2007 innotek GmbH
 
7
 *
 
8
 * This file is part of VirtualBox Open Source Edition (OSE), as
 
9
 * available from http://www.virtualbox.org. This file is free software;
 
10
 * you can redistribute it and/or modify it under the terms of the GNU
 
11
 * General Public License as published by the Free Software Foundation,
 
12
 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
 
13
 * distribution. VirtualBox OSE is distributed in the hope that it will
 
14
 * be useful, but WITHOUT ANY WARRANTY of any kind.
 
15
 */
 
16
 
 
17
#ifndef ___iprt_timer_h
 
18
#define ___iprt_timer_h
 
19
 
 
20
 
 
21
#include <iprt/cdefs.h>
 
22
#include <iprt/types.h>
 
23
 
 
24
 
 
25
__BEGIN_DECLS
 
26
 
 
27
/** @defgroup grp_rt_timer      RTTimer - Timer
 
28
 *
 
29
 * The IPRT timer API provides a simple abstraction of recurring and one-shot callback timers.
 
30
 *
 
31
 * Because of the great variation in the native APIs and the quality of
 
32
 * the service delivered by those native APIs, the timers are operated
 
33
 * on at best effort basis.
 
34
 *
 
35
 * All the ring-3 implementations are naturally at the mercy of the scheduler,
 
36
 * which means that the callback rate might vary quite a bit and we might skip
 
37
 * ticks. Many systems have a restriction that a process can only have one
 
38
 * timer. IPRT currently makes no efforts at multiplexing timers in those kind
 
39
 * of situations and will simply fail if you try to create more than one timer.
 
40
 *
 
41
 * Things are generally better in ring-0. The implementations will use interrupt
 
42
 * time callbacks wherever available, and if not, resort to a high priority
 
43
 * kernel thread.
 
44
 *
 
45
 * @ingroup grp_rt
 
46
 * @{
 
47
 */
 
48
 
 
49
 
 
50
/** Timer handle. */
 
51
typedef struct RTTIMER   *PRTTIMER;
 
52
 
 
53
/**
 
54
 * Timer callback function.
 
55
 *
 
56
 * The context this call is made in varies with different platforms and
 
57
 * kernel / user mode IPRT.
 
58
 *
 
59
 * In kernel mode a timer callback should not waste time, it shouldn't
 
60
 * waste stack and it should be prepared that some APIs might not work
 
61
 * correctly because of weird OS restrictions in this context that we
 
62
 * haven't discovered and avoided yet. Please fix those APIs so they
 
63
 * at least avoid panics and weird behaviour.
 
64
 *
 
65
 * @param   pTimer      Timer handle.
 
66
 * @param   pvUser      User argument.
 
67
 */
 
68
typedef DECLCALLBACK(void) FNRTTIMER(PRTTIMER pTimer, void *pvUser);
 
69
/** Pointer to FNRTTIMER() function. */
 
70
typedef FNRTTIMER *PFNRTTIMER;
 
71
 
 
72
 
 
73
/**
 
74
 * Create a recurring timer.
 
75
 *
 
76
 * @returns iprt status code.
 
77
 * @param   ppTimer             Where to store the timer handle.
 
78
 * @param   uMilliesInterval    Milliseconds between the timer ticks.
 
79
 *                              This is rounded up to the system granularity.
 
80
 * @param   pfnTimer            Callback function which shall be scheduled for execution
 
81
 *                              on every timer tick.
 
82
 * @param   pvUser              User argument for the callback.
 
83
 * @see     RTTimerDestroy, RTTimerStop
 
84
 */
 
85
RTDECL(int) RTTimerCreate(PRTTIMER *ppTimer, unsigned uMilliesInterval, PFNRTTIMER pfnTimer, void *pvUser);
 
86
 
 
87
/**
 
88
 * Create a suspended timer.
 
89
 *
 
90
 * @returns iprt status code.
 
91
 * @param   ppTimer             Where to store the timer handle.
 
92
 * @param   u64NanoInterval     The interval between timer ticks specified in nanoseconds if it's
 
93
 *                              a recurring timer. This is rounded to the fit the system timer granularity.
 
94
 *                              For one shot timers, pass 0.
 
95
 * @param   fFlags              Timer flags.
 
96
 * @param   pfnTimer            Callback function which shall be scheduled for execution
 
97
 *                              on every timer tick.
 
98
 * @param   pvUser              User argument for the callback.
 
99
 * @see     RTTimerStart, RTTimerStop, RTTimerDestroy, RTTimerGetSystemGranularity
 
100
 */
 
101
RTDECL(int) RTTimerCreateEx(PRTTIMER *ppTimer, uint64_t u64NanoInterval, unsigned fFlags, PFNRTTIMER pfnTimer, void *pvUser);
 
102
 
 
103
/** @name RTTimerCreateEx flags
 
104
 * @{ */
 
105
/** Any CPU is fine. (Must be 0.) */
 
106
#define RTTIMER_FLAGS_CPU_ANY        0
 
107
/** One specific CPU */
 
108
#define RTTIMER_FLAGS_CPU_SPECIFIC   BIT(8)
 
109
/** All online CPUs. */
 
110
#define RTTIMER_FLAGS_CPU_ALL        ( RTTIMER_FLAGS_CPU_MASK | RTTIMER_FLAGS_CPU_SPECIFIC )
 
111
/** CPU mask. */
 
112
#define RTTIMER_FLAGS_CPU_MASK       0xff
 
113
/** Convert a CPU number (0-based) to RTTimerCreateEx flags. 
 
114
 * This will automatically OR in the RTTIMER_FLAG_CPU_SPECIFIC flag. */
 
115
#define RTTIMER_FLAGS_CPU(iCpu)      ( (iCpu) | RTTIMER_FLAG_CPU_SPECIFIC )
 
116
/** Macro that validates the flags. */
 
117
#define RTTIMER_FLAGS_IS_VALID(fFlags) ( !((fFlags) & ((fFlags) & RTTIMER_FLAGS_CPU_SPECIFIC ? 0x1ff : 0x100)) )
 
118
/** @} */
 
119
 
 
120
/**
 
121
 * Stops and destroys a running timer.
 
122
 *
 
123
 * @returns iprt status code.
 
124
 * @param   pTimer      Timer to stop and destroy. NULL is ok.
 
125
 */
 
126
RTDECL(int) RTTimerDestroy(PRTTIMER pTimer);
 
127
 
 
128
/**
 
129
 * Stops an active timer.
 
130
 *
 
131
 * @returns IPRT status code.
 
132
 * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 
133
 * @retval  VERR_TIMER_ACTIVE if the timer isn't suspended.
 
134
 *
 
135
 * @param   pTimer      The timer to activate.
 
136
 * @param   u64First    The RTTimeSystemNanoTS() for when the timer should start firing.
 
137
 *                      If 0 is specified, the timer will fire ASAP.
 
138
 * @see     RTTimerStop
 
139
 */
 
140
RTDECL(int) RTTimerStart(PRTTIMER pTimer, uint64_t u64First);
 
141
 
 
142
/**
 
143
 * Stops an active timer.
 
144
 *
 
145
 * @returns IPRT status code.
 
146
 * @retval  VERR_INVALID_HANDLE if pTimer isn't valid.
 
147
 * @retval  VERR_TIMER_SUSPENDED if the timer isn't active.
 
148
 * @retval  VERR_NOT_SUPPORTED if the IPRT implementation doesn't support stopping a timer.
 
149
 *
 
150
 * @param   pTimer  The timer to suspend.
 
151
 * @see     RTTimerStart
 
152
 */
 
153
RTDECL(int) RTTimerStop(PRTTIMER pTimer);
 
154
 
 
155
 
 
156
/**
 
157
 * Gets the (current) timer granularity of the system.
 
158
 *
 
159
 * @returns The timer granularity of the system in nanoseconds.
 
160
 * @see     RTTimerRequestSystemGranularity
 
161
 */
 
162
RTDECL(uint32_t) RTTimerGetSystemGranularity(void);
 
163
 
 
164
/**
 
165
 * Requests a specific system timer granularity.
 
166
 *
 
167
 * Successfull calls to this API must be coupled with the exact same number of
 
168
 * calls to RTTimerReleaseSystemGranularity() in order to undo any changes made.
 
169
 *
 
170
 *
 
171
 * @returns IPRT status code.
 
172
 * @retval  VERR_NOT_SUPPORTED if the requested value isn't supported by the host platform
 
173
 *          or if the host platform doesn't support modifying the system timer granularity.
 
174
 * @retval  VERR_PERMISSION_DENIED if the caller doesn't have the necessary privilege to
 
175
 *          modify the system timer granularity.
 
176
 *
 
177
 * @param   u32Request      The requested system timer granularity in nanoseconds.
 
178
 * @param   pu32Granted     Where to store the granted system granularity. This is the value
 
179
 *                          that should be passed to  RTTimerReleaseSystemGranularity(). It
 
180
 *                          is what RTTimerGetSystemGranularity() would return immediately
 
181
 *                          after the change was made.
 
182
 *
 
183
 *                          The value differ from the request in two ways; rounding and
 
184
 *                          scale. Meaning if your request is for 10.000.000 you might
 
185
 *                          be granted 10.000.055 or 1.000.000.
 
186
 * @see     RTTimerReleaseSystemGranularity, RTTimerGetSystemGranularity
 
187
 */
 
188
RTDECL(int) RTTimerRequestSystemGranularity(uint32_t u32Request, uint32_t *pu32Granted);
 
189
 
 
190
/**
 
191
 * Releases a system timer granularity grant acquired by RTTimerRequestSystemGranularity().
 
192
 *
 
193
 * @returns IPRT status code.
 
194
 * @retval  VERR_NOT_SUPPORTED if the host platform doesn't have any way of modifying
 
195
 *          the system timer granularity.
 
196
 * @retval  VERR_WRONG_ORDER if nobody call RTTimerRequestSystemGranularity() with the
 
197
 *          given grant value.
 
198
 * @param   u32Granted      The granted system granularity.
 
199
 * @see     RTTimerRequestSystemGranularity
 
200
 */
 
201
RTDECL(int) RTTimerReleaseSystemGranularity(uint32_t u32Granted);
 
202
 
 
203
/** @} */
 
204
 
 
205
__END_DECLS
 
206
 
 
207
#endif