Kernel Functions for Drivers                        untimeout(9F)



NAME
     untimeout - cancel previous timeout function call

SYNOPSIS
     #include 
     #include 



     clockt untimeout(timeoutidt id);


INTERFACE LEVEL
     Architecture independent level 1 (DI/DKI).

PARAMETERS
     id    Opaque timeout ID from a previous timeout(9F) call.


DESCRIPTION
     The  untimeout()  function  cancels  a  pending  timeout(9F)
     request. untimeout() will not return until the pending call-
     back is  cancelled  or  has  run.  Because  of  this,  locks
     acquired  by  the callback routine should not be held across
     the call to untimeout() or a deadlock may result.


     Since  no  mutex  should  be  held  across   the   call   to
     untimeout(),   there   is   a  race  condition  between  the
     occurrence of an expected event and  the  execution  of  the
     timeout  handler.  In particular, it should be noted that no
     problems will result from calling untimeout() for a  timeout
     which  is either running on another CPU, or has already com-
     pleted. Drivers should be structured with the  understanding
     that the arrival of both an interrupt and a timeout for that
     interrupt can occasionally occur, in either order.

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

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

EXAMPLES
     In the following example, the device driver has issued an IO
     request  and  is  waiting  for the device to respond. If the
     device does not respond within 5 seconds, the device  driver
     will print out an error message to the console.




SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                        untimeout(9F)



       static void
       xxtimeouthandler(void *arg)
       {
               struct xxstate *xsp = (struct xxstate *)arg;
               mutexenter(&xsp->lock);
               cvsignal(&xsp->cv);
               xsp->flags = TIMEDOUT;
               mutexexit(&xsp->lock);
               xsp->timeoutid = 0;
       }
       static uintt
       xxintr(caddrt arg)
       {
               struct xxstate *xsp = (struct xxstate *)arg;
                .
                .
                .
               mutexenter(&xsp->lock);
               /* Service interrupt */
               cvsignal(&xsp->cv);
               mutexexit(&xsp->lock);
               if (xsp->timeoutid != 0) {
                       (void) untimeout(xsp->timeoutid);
                       xsp->timeoutid = 0;
               }
               return(DINTRCLAIMED);
       }
       static void
       xxcheckcond(struct xxstate *xsp)
       {
                .
                .
                .
               xsp->timeoutid = timeout(xxtimeouthandler,
                   xsp, (5 * drvusectohz(1000000)));
               mutexenter(&xsp->lock);
               while (/* Waiting for interrupt  or timeout*/)
                       cvwait(&xsp->cv, &xsp->lock);
               if (xsp->flags & TIMEDOUT)
                       cmnerr(CEWARN, "Device not responding");
                .
                .
                .
               mutexexit(&xsp->lock);
                .
                .
                .
       }


SEE ALSO




SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                        untimeout(9F)



     open(9E),   cvsignal(9F),    cvwaitsig(9F),    delay(9F),
     timeout(9F)


     Writing Device Drivers


















































SunOS 5.11          Last change: 16 Jan 2006                    3