usr/src/man/man9f/drv_usectohz.9f

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH DRV_USECTOHZ 9F "Apr 24, 2008"
   8 .SH NAME
   9 drv_usectohz \- convert microseconds to clock ticks
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/types.h>
  14 #include <sys/ddi.h>
  15
  16
  17
  18 \fBclock_t\fR \fBdrv_usectohz\fR(\fBclock_t\fR \fImicrosecs\fR);
  19 .fi
  20
  21 .SH INTERFACE LEVEL
  22 .sp
  23 .LP
  24 Architecture independent level 1 (DDI/DKI).
  25 .SH PARAMETERS
  26 .sp
  27 .ne 2
  28 .na
  29 \fB\fImicrosecs\fR\fR
  30 .ad
  31 .RS 13n
  32 The number of microseconds to convert.
  33 .RE
  34
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 The \fBdrv_usectohz()\fR function converts a length of time expressed in
  39 microseconds to a number of system clock ticks. The time arguments to
  40 \fBtimeout\fR(9F) and \fBdelay\fR(9F) are expressed in clock ticks.
  41 .sp
  42 .LP
  43 The \fBdrv_usectohz()\fR function is a portable interface for drivers to make
  44 calls to \fBtimeout\fR(9F) and \fBdelay\fR(9F) and remain binary compatible
  45 should the driver object file be used on a system with a different clock speed
  46 (a different number of ticks in a second).
  47 .SH RETURN VALUES
  48 .sp
  49 .LP
  50 The value returned is the number of system clock ticks equivalent to the
  51 \fImicrosecs\fR argument. No error value is returned. If the clock tick
  52 equivalent to \fImicrosecs\fR is too large to be represented as a
  53 \fBclock_t\fR, then the maximum \fBclock_t\fR value will be returned.
  54 .SH CONTEXT
  55 .sp
  56 .LP
  57 The \fBdrv_usectohz()\fR function can be called from user, interrupt, or kernel
  58 context.
  59 .SH SEE ALSO
  60 .sp
  61 .LP
  62 \fBdelay\fR(9F), \fBdrv_hztousec\fR(9F), \fBtimeout\fR(9F)
  63 .sp
  64 .LP
  65 \fIWriting Device Drivers\fR
  66 .SH NOTES
  67 .sp
  68 .LP
  69 If the \fImicrosecs\fR argument to \fBdrv_usectohz()\fR is less than
  70 \fBdrv_hztousec\fR(9F), \fBdrv_usectohz()\fR returns one tick. This, coupled
  71 with multiplication, can result in significantly longer durations than
  72 expected. For example, on a machine where \fBhz\fR is 100, calling
  73 \fBdrv_usectohz()\fR with a \fImicrosecs\fR value less than 10000 returns a
  74 result equivalent to 10000 (1 tick). This type of mistake causes code such
  75 as"5000 * drv_usectohz(1000)" to compute a duration of 50 seconds instead of
  76 the intended 5 seconds.