Manpage of DRV_HZTOUSEC

DRV_HZTOUSEC

Section: Linux Fast-STREAMS DDI/DKI (9)
Updated: 2008-10-31
Index Return to Main Contents

NAME

drv_hztousec, drv_usectohz, drv_hztomsec, drv_msectohz - convert kernel tick time between microseconds or milliseconds

SYNOPSIS

#include <sys/types.h>
#include <sys/dki.h>

clock_t drv_hztousec(clock_t hertz);
clock_t drv_hztomsec(clock_t hertz);
clock_t drv_usectohz(clock_t usec);
clock_t drv_msectohz(clock_t msec);

ARGUMENTS

hertz: the time value in ticks to convert to milliseconds or microseconds.
usec: the time value in microseconds to convert to ticks.
msec: the time value in milliseconds to convert to ticks.

INTERFACE

DDI/DKI.

DESCRIPTION

drv_hztousec() drv_hztomsec() drv_usectohz() and drv_msectohz() provide a mechanism for converting between kernel tick time and an absolute time unit (microseconds or milliseconds). Use of these functions permit driver code to be architecturally independent from the quantum of the kernel tick clock.

drv_hztousec() accepts a kernel tick clock time as the hertz argument and returns the time in microseconds. drv_hztomsec() accepts a kernel tick clock time as the hertz argument and returns the time in milliseconds. drv_usectohz() accepts a time interval in microseconds in the usec argument and returns the time in clock ticks. drv_msectohz() accepts a time interval in milliseconds in the msec argument and returns the time in clock ticks.

These functions are useful in conjunction with timeout(9) and qtimeout(9) which only accept timeout durations in system ticks.

RETURN

drv_usectohz() and drv_msectohz() return the time value in ticks. drv_hztousec() returns the time value in microseconds. drv_hztomsec() returns the time value in milliseconds.

ERRORS

drv_hztousec(), drv_hztomsec(), drv_usectohz() and drv_msectohz() always succeed.

CONTEXT

drv_hztousec(), drv_hztomsec(), drv_usectohz() and drv_msectohz() can be called from any context, including user context, module procedures, callouts, callbacks, soft interrupts (tasklets and bottom halves), and interrupt service routines.

MP-STREAMS

drv_hztousec(), drv_hztomsec(), drv_usectohz() and drv_msectohz() are MP safe.

NOTICES

drv_hztousec(), drv_hztomsec(), drv_usectohz() and drv_msectohz() are implemented by performing simple calculations using jiffies(9) and HZ(9). There are defined as extern inline functions and with optimization these calculations will be inline.

drv_usectohz() and drv_msectohz() always truncate to the next lowest integer tick value. This means that, when converting a value less than a tick, the result will always be 0 ticks. This makes these functions unsafe for use directly with timeout(9) and qtimeout(9). The caller should test whether the result is zero before passing it to timeout(9) or qtimeout(9), unless it is acceptable to cause a possibly immediate timeout callback.

Care should be taken with the drv_hztousec() function, as coverted value can easily overflow a clock_t. Portable STREAMS drivers and modules will only convert differences between successive calls to drv_getparm(9) or retrieval of lbolt(9) with drv_hztousec() instead of converting each value (possibly causing an overflow on each) and then taking the difference.

BUGS

These functions have no known bugs in LfS[1].

COMPATIBILITY

drv_hztousec(), drv_hztomsec(), drv_usectohz() and drv_msectohz() are source-level compatible with SVR 4.2 MP DDI/DKI[2], and implementations based on SVR 4.2[3], with the following portability considerations:

---: LiS[4] does not provide these functions. LiS provide a completely non-standard and non-portable set of functions, lis_time_till(9), lis_target_time(9), liz_usectohz(9), and lis_milli_to_ticks(9). Of these, lis_uzectohz(9) and lis_milli_to_ticks(9) are equivalent to drv_usectohz() and drv_msectohz().
: Portable STREAMS drivers and modules will use Linux Fast-STREAMS instead of LiS.
---: Later Linux kernels provide the functions jiffies_to_msecs(9), msecs_to_jiffies(9), and jiffies_to_usecs(9), and these are used where available to implement drv_hztomsec(), drv_msectohz(), and drv_hztousec(), respectively.
---: Binary compatibility is not guaranteed.

See STREAMS(9) for additional compatibility information.

CONFORMANCE

drv_hztousec() and drv_usectohz() conform to SVR 4.2 MP DDI/DKI[2].

drv_hztomsec() and drv_msectohz() are Linux Fast-STREAMS specific.

HISTORY

drv_hztousec() and drv_usectohz() first appeared in SVR 4[5].

REFERENCES

[1]: streams-0.9.2, Linux Fast-STREAMS (LfS) 0.9.2 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[2]: USL DDI/DKI, Device Driver Interface/Driver-Kernel Interface (DDI/DKI) Reference Manual for Intel Processors, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[3]: SVR 4.2, UNIX® System V Release 4.2 Programmer's Manual, 1992, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.
[4]: LIS 2.18, Linux STREAMS (LiS) 2.18.6 Source Code, Brian Bidulock, ed., OpenSS7 Corporation. <http://www.openss7.org/>
[5]: SVR 4, UNIX® System V Release 4 Programmer's Manual, 1990, (Englewood Cliffs, New Jersey), AT&T UNIX System Laboratories, Inc., Prentice Hall.

TRADEMARKS

OpenSS7tm: is a trademark of OpenSS7 Corporation.
Linux®: is a registered trademark of Linus Torvalds.
UNIX®: is a registered trademark of The Open Group.
Solaris®: is a registered trademark of Sun Microsystems.

Other trademarks are the property of their respective owners.

IDENTIFICATION

Linux Fast-STREAMS: Package streams version 0.9.2.4 released 2008-10-31.

Index

NAME
SYNOPSIS
ARGUMENTS
INTERFACE
DESCRIPTION
RETURN
ERRORS
CONTEXT
MP-STREAMS
NOTICES
SEE ALSO
BUGS
COMPATIBILITY
CONFORMANCE
HISTORY
REFERENCES
TRADEMARKS
IDENTIFICATION

This document was created by man2html, using the manual pages.
Time: 11:58:22 GMT, May 25, 2013