untimeout(9f)

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

NAME

6       untimeout - cancel previous timeout function call
7

SYNOPSIS

9       #include <sys/types.h>
10       #include <sys/conf.h>
11
12
13
14       clock_t untimeout(timeout_id_t id);
15
16

INTERFACE LEVEL

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

PARAMETERS

21       id    Opaque timeout ID from a previous timeout(9F) call.
22
23

DESCRIPTION

25       The untimeout() function cancels a pending timeout(9F) request. untime‐
26       out() will not return until the pending callback is  cancelled  or  has
27       run. Because of this, locks acquired by the callback routine should not
28       be held across the call to untimeout() or a deadlock may result.
29
30
31       Since no mutex should be held across the call to untimeout(), there  is
32       a  race  condition  between the occurrence of an expected event and the
33       execution of the timeout handler. In particular,  it  should  be  noted
34       that  no  problems  will  result from calling untimeout() for a timeout
35       which is either running on another CPU, or has already completed. Driv‐
36       ers  should  be  structured  with the understanding that the arrival of
37       both an interrupt and a timeout for  that  interrupt  can  occasionally
38       occur, in either order.
39

RETURN VALUES

41       The  untimeout() function returns -1 if the id is not found. Otherwise,
42       it returns an integer value greater than or equal to 0.
43

CONTEXT

45       The untimeout() function can be called from user, interrupt, or  kernel
46       context.
47

EXAMPLES

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