SVR5

TICKS(D3)

TICKS -- macros for lbolt values

Synopsis

   #include <sys/types.h>
   #include <sys/clock.h>
   #include <sys/ddi.h>
   
   clock_t TICKS(void);
   

   clock_t TICKS_SINCE(clock_t start_ticks);
   

   clock_t TICKS_BETWEEN(clock_t start_ticks, clock_t end_ticks);
   

   clock_t TICKS_FARPAST(void);
   

   clock_t TICKS_FARFUTURE(void);
   

   int TICKS_LATER(clock_t ticks1, clock_t ticks2);

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, ticks1, ticks2: lbolt values as returned by the TICKS( ), TICKS_FARFUTURE( ), or TICKS_FARPAST( ) 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 drv_hztousec(D3) and drv_usectohz(D3) functions.
TICKS_FARPAST: Returns an lbolt value that represents a time "far in the past." Assuming a typical 100 ticks per second, the value returned represents a time approximately four months prior to the time of the call.
TICKS_FARFUTURE: Returns an lbolt value that represents a time "far in the future." Assuming a typical 100 ticks per second, the value returned represents a time approximately four months beyond the time of the call.

The lbolt counter underlying TICKS( ), TICKS_FARPAST( ), and TICKS_FARFUTURE( ) 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 - CLOCK_MAX] through [current_lbolt + CLOCK_MAX]

can be represented. See ``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 CLOCK_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 CLOCK_MAX ticks in the past.
TICKS_LATER: Returns TRUE if the time represented by ticks1 is chronologically later than the time represented by ticks2; otherwise returns FALSE. ticks1 and ticks2 must be less than CLOCK_MAX ticks apart.

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 = drv_hztousec(TICKS_SINCE(start_time));

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 = drv_hztousec(TICKS_BETWEEN(start_time, current_lbolt));

The comparison macro TICKS_LATER( ) is the only means for determining the relative vintage of two lbolt-based timestamps when a driver has no way of knowing which is earlier; it is rarely needed because such situations typically do not arise. As a matter of style, it is suggested that drivers avoid using TICKS_LATER( ) unnecessarily or introducing circumstances in which TICKS_LATER( ) must be used, such as:

   /* DON'T DO THIS */
   end_time = TICKS() + timeout_ticks;
   
   /* ...perform some device operation... */
   

   if (TICKS_LATER(TICKS(), end_time)) {
   	/* operation took too long */

The same effect is better achieved using the first example above.

The TICKS_FARPAST( ) and TICKS_FARFUTURE( ) macros are generally used to provide boundary values for algorithms involving TICKS_LATER( ), and are also rarely needed. Be aware that a TICKS_FARFUTURE( ) value ages over time and eventually falls back into the past. Similarly, a TICKS_FARPAST( ) value will eventually look like a future time as lbolt approaches it in circular fashion. TICKS_FARPAST( ) and TICKS_FARFUTURE( ) values obtained at widely-separated times may not appear to bear the expected relationship when compared using the TICKS_LATER( ) macro. For similar reasons, it is wise to avoid any situation where a timestamp value may linger in the system for long periods of time (on the order of months).

Do not use any value, including zero, to represent a special case when interpreting the return values of the TICKS( ), TICKS_FARPAST( ), and TICKS_FARFUTURE( ) macros, since they 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.

Hardware applicability

All

Version applicability

ddi: 8, 8mp

Differences between versions

DDI versions prior to version 8 must use the drv_getparm(D3) function to access the lbolt value. drv_getparm( ) can be used in this way for DDI 8 drivers, but the TICKS( ) family of macros are a better alternative.

Future directions

The lbolt global variable may be eliminated in a future release.

SCO OpenServer ODDI compatibility

Beginning with ODDI 5 (SCO OpenServer Release 5.0.5), SCO OpenServer supports the same TICKS(D3oddi) macro set as SVR5.

UDI compatibility

UDI drivers use timing functions that are system independent rather than accessing lbolt directly. Use udi_time_current( ) to replace calls to drv_getparam(lbolt). udi_time_between( ) and udi_time_since( ) can be used in place of the traditional algorithms that capture timing information with lbolt. See ``lbolt'' in HDK Technical Reference for more information.

References

drv_getparm(D3), drv_hztousec(D3), TICKS(D3oddi)

``CLOCK_MAX'' in HDK Technical Reference
``lbolt'' in HDK Technical Reference