timeout(9f) - osol9

1timeout(9F)              Kernel Functions for Drivers              timeout(9F)
2
3
4

NAME

6       timeout - execute a function after a specified length of time
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/conf.h>
11
12
13
14       timeout_id_t timeout(void (* func)(void *), void *arg,
15            clock_t  ticks);
16
17

INTERFACE LEVEL

19       Architecture independent level 1 (DDI/DKI).
20

PARAMETERS

22       func     Kernel function to invoke when the time increment expires.
23
24
25       arg      Argument to the function.
26
27
28       ticks    Number  of  clock ticks to wait before the function is called.
29                Use drv_usectohz(9F) to convert microseconds to clock ticks.
30
31

DESCRIPTION

33       The timeout() function schedules the specified function  to  be  called
34       after a specified time interval. The exact time interval over which the
35       timeout takes effect cannot be guaranteed, but the  value  given  is  a
36       close approximation.
37
38
39       The  function  called by timeout() must adhere to the same restrictions
40       as a driver soft interrupt handler.
41
42
43       The delay(9F) function calls timeout(). Because timeout() is subject to
44       priority  inversion,  drivers waiting on behalf of processes with real-
45       time constraints should use cv_timedwait(9F) rather than delay().
46

RETURN VALUES

48       The timeout() function returns an opaque  non-zero  timeout  identifier
49       that can be passed to untimeout(9F) to cancel the request.
50

CONTEXT

52       The  timeout()  function  can be called from user, interrupt, or kernel
53       context.
54

EXAMPLES

56       Example 1 Using timeout()
57
58
59       In the following example, the device driver has issued  an  IO  request
60       and  is  waiting  for  the  device  to  respond. If the device does not
61       respond within 5 seconds, the device driver will  print  out  an  error
62       message to the console.
63
64
65         static void
66         xxtimeout_handler(void *arg)
67         {
68                 struct xxstate *xsp = (struct xxstate *)arg;
69                 mutex_enter(&xsp->lock);
70                 cv_signal(&xsp->cv);
71                 xsp->flags |= TIMED_OUT;
72                 mutex_exit(&xsp->lock);
73                 xsp->timeout_id = 0;
74         }
75         static uint_t
76         xxintr(caddr_t arg)
77         {
78                 struct xxstate *xsp = (struct xxstate *)arg;
79                  .
80                  .
81                  .
82                 mutex_enter(&xsp->lock);
83                 /* Service interrupt */
84                 cv_signal(&xsp->cv);
85                 mutex_exit(&xsp->lock);
86                 if (xsp->timeout_id != 0) {
87                         (void) untimeout(xsp->timeout_id);
88                         xsp->timeout_id = 0;
89                 }
90                 return(DDI_INTR_CLAIMED);
91         }
92         static void
93         xxcheckcond(struct xxstate *xsp)
94         {
95                  .
96                  .
97                  .
98                 xsp->timeout_id = timeout(xxtimeout_handler,
99                     xsp, (5 * drv_usectohz(1000000)));
100                 mutex_enter(&xsp->lock);
101                 while (/* Waiting for interrupt  or timeout*/)
102                         cv_wait(&xsp->cv, &xsp->lock);
103                 if (xsp->flags & TIMED_OUT)
104                         cmn_err(CE_WARN, "Device not responding");
105                  .
106                  .
107                  .
108                 mutex_exit(&xsp->lock);
109                  .
110                  .
111                  .
112         }
113
114