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

   1 '\" te
   2 .\" Copyright (c) 2001, 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 DELAY 9F "Oct 15, 2001"
   8 .SH NAME
   9 delay \- delay execution for a specified number of clock ticks
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <sys/ddi.h>
  14
  15
  16
  17 \fBvoid\fR \fBdelay\fR(\fBclock_t\fR \fIticks\fR);
  18 .fi
  19
  20 .SH INTERFACE LEVEL
  21 .sp
  22 .LP
  23 Architecture independent level 1 (DDI/DKI).
  24 .SH PARAMETERS
  25 .sp
  26 .ne 2
  27 .na
  28 \fB\fIticks\fR \fR
  29 .ad
  30 .RS 10n
  31 The number of clock cycles to delay.
  32 .RE
  33
  34 .SH DESCRIPTION
  35 .sp
  36 .LP
  37 \fBdelay()\fR provides a mechanism for a driver to delay its execution for a
  38 given period of time. Since the speed of the clock varies among systems,
  39 drivers should base their time values on microseconds and use
  40 \fBdrv_usectohz\fR(9F) to convert microseconds into clock ticks.
  41 .sp
  42 .LP
  43 \fBdelay()\fR uses \fBtimeout\fR(9F) to schedule an internal function to be
  44 called after the specified amount of time has elapsed. \fBdelay()\fR then waits
  45 until the function is called. Because \fBtimeout()\fR is subject to priority
  46 inversion, drivers waiting on behalf of processes with real-time constraints
  47 should use \fBcv_timedwait\fR(9F) rather than \fBdelay()\fR.
  48 .sp
  49 .LP
  50 \fBdelay()\fR does not busy-wait. If busy-waiting is required, use
  51 \fBdrv_usecwait\fR(9F).
  52 .SH CONTEXT
  53 .sp
  54 .LP
  55 \fBdelay()\fR can be called from user and kernel contexts.
  56 .SH EXAMPLES
  57 .LP
  58 \fBExample 1 \fR\fBdelay()\fR Example
  59 .sp
  60 .LP
  61 Before a driver I/O routine allocates buffers and stores any user data in them,
  62 it checks the status of the device (line 12). If the device needs manual
  63 intervention (such as, needing to be refilled with paper), a message is
  64 displayed on the system console (line 14). The driver waits an allotted time
  65 (line 17) before repeating the procedure.
  66
  67 .sp
  68 .in +2
  69 .nf
  70  1  struct  device  {   /* layout of physical device registers */
  71  2          int      control;   /* physical device control word */
  72  3          int      status;    /* physical device status word */
  73  4          short    xmit_char; /* transmit character to device */
  74  5  };
  75  6
  76  7
  77        . . .
  78  9      /* get device registers  */
  79 10      register struct device *rp = ...
  80 11
  81 12      while (rp->status & NOPAPER) {  /* while printer is out of paper */
  82 13          /* display message and ring bell */
  83             /* on system console */
  84 14          cmn_err(CE_WARN, "^\e007",
  85 15                            (getminor(dev) & 0xf));
  86 16          /* wait one minute and try again */
  87 17          delay(60 * drv_usectohz(1000000));
  88 18      }
  89 .fi
  90 .in -2
  91
  92 .SH SEE ALSO
  93 .sp
  94 .LP
  95 \fBbiodone\fR(9F), \fBbiowait\fR(9F), \fBcv_timedwait\fR(9F),
  96 \fBddi_in_panic\fR(9F), \fBdrv_hztousec\fR(9F), \fBdrv_usectohz\fR(9F),
  97 \fBdrv_usecwait\fR(9F), \fBtimeout\fR(9F), \fBuntimeout\fR(9F)
  98 .sp
  99 .LP
 100 \fIWriting Device Drivers\fR