Kernel Functions for Drivers                          timeout(9F)



NAME
     timeout - execute a function after  a  specified  length  of
     time

SYNOPSIS
     #include 
     #include 



     timeoutidt timeout(void (* func)(void *), void *arg,
          clockt  ticks);


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

PARAMETERS
     func     Kernel function to invoke when the  time  increment
              expires.


     arg      Argument to the function.


     ticks    Number of clock ticks to wait before  the  function
              is   called.   Use   drvusectohz(9F)   to  convert
              microseconds to clock ticks.


DESCRIPTION
     The timeout() function schedules the specified  function  to
     be  called  after  a specified time interval. The exact time
     interval over which  the  timeout  takes  effect  cannot  be
     guaranteed, but the value given is a close approximation.


     The function called by timeout() must  adhere  to  the  same
     restrictions as a driver soft interrupt handler.


     The delay(9F) function calls timeout(). Because timeout() is
     subject  to priority inversion, drivers waiting on behalf of
     processes   with   real-time    constraints    should    use
     cvtimedwait(9F) rather than delay().

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





SunOS 5.11          Last change: 16 Jan 2006                    1






Kernel Functions for Drivers                          timeout(9F)



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

EXAMPLES
     Example 1 Using timeout()


     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.


       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);



SunOS 5.11          Last change: 16 Jan 2006                    2






Kernel Functions for Drivers                          timeout(9F)



               if (xsp->flags & TIMEDOUT)
                       cmnerr(CEWARN, "Device not responding");
                .
                .
                .
               mutexexit(&xsp->lock);
                .
                .
                .
       }


SEE ALSO
     bufcall(9F), cvtimedwait(9F), ddiinpanic(9F),  delay(9F),
     drvusectohz(9F), untimeout(9F)


     Writing Device Drivers





































SunOS 5.11          Last change: 16 Jan 2006                    3