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