SVR5

dtimeout(D3)

dtimeout -- execute a function on a specified processor after a specified length of time

Synopsis (Not in current DDI version)

   #include <sys/types.h>
   #include <sys/ddi.h>
   
   toid_t dtimeout(void (*fn)(), void *arg, long ticks, pl_t pl,
   			processorid_t processor);

Description

dtimeout causes the function specified by fn to be called after the time interval specified by ticks, on the processor specified by processor, at the interrupt priority level specified by pl. arg will be passed as the only argument to function fn. The dtimeout call returns immediately without waiting for the specified function to execute.

Arguments

fn

Function to execute on the specified processor when the time increment expires. The function specified by fn runs in interrupt context in HDK Technical Reference and must not lower the interrupt priority below that specified by the pl argument." fn will be run at some point after the time interval expires. Like a device interrupt (see intr(D2)), it may need to be deferred until the interrupt priority is dropped to a sufficiently low level. Timer callback functions are only run when the interrupt priority level is plbase; they never interrupt device interrupt handlers.

arg

Argument to the function.

ticks

Number of clock ticks to wait before the function is called. The length of time before the function is called is not guaranteed to be exactly equal to the requested time, but will be at least ticks-1 clock ticks in length.

A ticks argument of 0 has the same effect as a ticks argument of 1. Both will result in an approximate wait of between 0 and 1 tick (possibly longer).

The flag TO_PERIODIC can be logically OR'ed into the ticks argument to indicate a repeating periodic timer. When this is used, the specified function will be called every ticks clock ticks, instead of just once; successive calls will compensate for any delay in a previous cycle, so that there is no cumulative drift. The repeating timer can be canceled by untimeout(D3), just like any other timeout.

pl

The interrupt priority level at which the function will be called. pl must specify a priority level greater than or equal to pltimeout, so plbase cannot be used. See pl(D5) for a list of values for pl.

processor

Processor on which the function must execute.

Return values

If the function specified by fn is successfully scheduled, dtimeout( ) returns a non-zero identifier that can be passed to untimeout( ) to cancel the request. If the function could not be scheduled on the specified processor, dtimeout( ) returns a value of 0.

Usage

This directed timeout capability provides a form of dynamic processor binding for driver code.

Drivers should be careful to cancel any pending dtimeout( ) functions that access data structures before these structures are de-initialized or deallocated.

Context and synchronization

Non-blockable, interrupt, user, or blockable context.

Hardware applicability

All

Version applicability

ddi: 3, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp

Differences between versions

dtimeout( ) is not supported in DDI 8.

References

itimeout(D3), LOCK_ALLOC(D3), untimeout(D3)

``Timeouts'' in HDK Technical Reference