SCO OpenServer
TICKS(D3oddi)
TICKS --
macros for lbolt values
Synopsis
#include <sys/types.h>
#include <sys/btok.h>
clock_t TICKS(void);
clock_t TICKS_BETWEEN(clock_t t1, clock_t t2);
clock_t TICKS_SINCE(clock_t t);
Description
The
TICKS( )
macros allow access to and comparison of
lbolt
values.
The lbolt global variable
should never be referenced directly,
nor should saved lbolt values be compared
except with these macros.
Arguments
start_ticks, end_ticks-
lbolt values as returned by the
TICKS( )
macro.
Return values
The following macros return absolute lbolt values:
TICKS-
Returns the current lbolt value,
which is the time in ticks since the system was booted.
A tick is an implementation-dependent time period,
typically 1/100 of a second.
Drivers should not build in any assumptions
about the length of a tick,
but can convert between ticks and microseconds using the
a calculation with the Hz kernel variable
that represents the approximate number of ticks per second.
The lbolt counter underlying
TICKS( )
is of finite size and will wrap around
if the system stays up long enough.
At any given moment,
only times in the range:
[current_lbolt - ULONG_MAX] through [current_lbolt + ULONG_MAX]
can be represented.
ULONG_MAX is discussed in
``CLOCK_MAX'' in HDK Technical Reference.
Assuming 100 ticks-per-second,
this is a range of 497 days,
248 before and 248 after the current day.
The representation is signed;
these macros can return a value
that is negative, zero, or positive.
The following macros compare lbolt values:
TICKS_BETWEEN-
Returns the elapsed time in ticks between
the two times represented by the arguments.
If start_ticks and end_ticks
represent times more than ULONG_MAX ticks apart,
or end_ticks precedes start_ticks,
the result is undefined.
TICKS_SINCE-
Returns the elapsed time in ticks that has passed
since the time represented by start_ticks.
The result is undefined
if start_ticks represents a future time
or a time more than ULONG_MAX ticks in the past.
Usage
TICKS( )
and
TICKS_SINCE( )
suffice to deal with most needs
for which drivers have traditionally used
the lbolt variable.
A common paradigm is:
start_time = TICKS();
/* ...perform some device operation... */
if (TICKS_SINCE(start_time) > timeout_ticks) {
/* operation took too long */
}
Performance instrumentation code
will often contain sequences such as:
start_time = TICKS();
/* ...perform some device operation... */
/* see how long the operation took, in microseconds */
interval = (TICKS_SINCE(start_time)/Hz);
TICKS_BETWEEN( )
is seen less often,
and then usually to perform the same calculation as
TICKS_SINCE( )
when the current lbolt value
is already available from another source, as in:
interval = (TICKS_BETWEEN(start_time, current_lbolt)/Hz);
Do not use any value, including zero,
to represent a special case
when interpreting the return values of the
TICKS( ),
macro, since it will periodically return that value
if the system stays up indefinitely.
See
``lbolt'' in HDK Technical Reference
for more details about pitfalls involved
when doing arithmetic manipulations and comparisons
of lbolt values.
Context and synchronization
All
contexts.
Version applicability
oddi:
5, 5mp, 6, 6mp
Differences between versions
ODDI versions prior to version 5
do not support the
TICKS( )
family of macros.
Drivers must access the lbolt variable directly,
being sure to use it correctly; see
``lbolt'' in HDK Technical Reference.
Future directions
The lbolt global variable may be eliminated
in a future release.
SVR5 DDI compatibility
These same macros are supported in DDI 8
and later versions.
See the
TICKS(D3)
manual page for details.
Minor coding modifications are required to use
drv_hztousec(D3)
rather than calculations involving the Hz variable,
and the ULONG_MAX constant
is replaced by the CLOCK_MAX constant.
DDI 8 also supports two additional macros,
TICKS_FARPAST( )
and
TICKS_FARFUTURE( ),
that are not supported for ODDI drivers.
References
TICKS(D3)
``CLOCK_MAX'' in HDK Technical Reference
``lbolt'' in HDK Technical Reference
19 June 2005
© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 5 HDK - June 2005