93 lines
3.2 KiB
Plaintext
93 lines
3.2 KiB
Plaintext
.if n .pH ddi.rm/d3/386/dtimeout @(#)dtimeout 43.8 of 11/27/92
|
|
.\" Copyright 1991, 1992 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 AT&T
|
|
.TH dtimeout D3
|
|
.IX "\f4dtimeout\fP(D3)"
|
|
.SH NAME
|
|
\f4dtimeout\fP \- execute a function on a specified processor after a specified length of time
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.na
|
|
.ft 4
|
|
#include <sys/types.h>
|
|
#include <sys/ddi.h>
|
|
.sp 0.4
|
|
toid_t dtimeout(void (*\f2fn\fP)(), void *\f2arg\fP, long \f2ticks\fP, pl_t \f2pl\fP,
|
|
processorid_t \f2processor\fP, \f2arg2\fP, \f2arg3\fP, \f2arg4\fP);
|
|
.ft 1
|
|
.ad
|
|
.fi
|
|
.SS Arguments
|
|
.RS 0
|
|
.IP "\f2fn\fP" 12n
|
|
Function to execute on the specified processor when the time increment
|
|
expires.
|
|
.IP "\f2arg, arg2, arg3, arg4\fP" 12n
|
|
Argument to the function.
|
|
.IP "\f2ticks\fP" 12n
|
|
Number of clock ticks to wait before the function is called.
|
|
.IP "\f2pl\fP" 12n
|
|
The interrupt priority level at which the function will be called.
|
|
.IP "\f2processor\fP" 12n
|
|
Processor on which the function must execute.
|
|
.RE
|
|
.SH DESCRIPTION
|
|
\f4dtimeout\fP causes the function specified by \f2fn\fP to be
|
|
called after the time interval specified by \f2ticks\fP,
|
|
on the processor specified by \f2processor\fP,
|
|
at the interrupt priority level specified by \f2pl\fP.
|
|
\f2arg\fP will be passed as the only argument to function \f2fn\fP.
|
|
The \f4dtimeout\fP call returns immediately without waiting for the specified
|
|
function to execute.
|
|
.SS "Return Values"
|
|
If the function specified by \f2fn\fP is successfully scheduled, \f4dtimeout\fP
|
|
returns a non-zero identifier that can be passed to \f4untimeout\fP to cancel
|
|
the request.
|
|
If the function could not be scheduled on the specified processor, \f4dtimeout\fP
|
|
returns a value of 0.
|
|
.SH USAGE
|
|
This directed timeout capability provides a form of dynamic processor binding
|
|
for driver code.
|
|
.P
|
|
Drivers should be careful to cancel any pending \f4dtimeout\fP functions
|
|
that access data structures
|
|
before these structures are de-initialized or deallocated.
|
|
.SS "fn Argument"
|
|
The function specified by \f2fn\fP must not
|
|
lower the priority level below \f2pl\fP.
|
|
.P
|
|
After the time interval has expired, \f2fn\fP only runs if the processor is
|
|
at base level.
|
|
Otherwise, \f2fn\fP is deferred until some time in the near future.
|
|
.P
|
|
If \f4dtimeout\fP is called holding a lock
|
|
that is contended for by \f2fn\fP,
|
|
the caller must hold the lock at a processor level
|
|
greater than the base processor level.
|
|
.SS "ticks Argument"
|
|
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 \f2ticks\-1\fP
|
|
clock ticks in length.
|
|
.P
|
|
A \f2ticks\fP argument of 0 has the same effect as a \f2ticks\fP argument of 1.
|
|
Both will result in an approximate wait of between 0 and 1 tick
|
|
(possibly longer).
|
|
.SS "pl Argument"
|
|
\f2pl\fP must specify a priority level
|
|
greater than or equal to \f2pltimeout\fP;
|
|
thus, \f2plbase\fP cannot be used.
|
|
See \f4LOCK_ALLOC\fP(D3) for a list of values for \f2pl\fP.
|
|
Your driver should treat pl as an "opaque" and should not
|
|
try to compare or do any operation
|
|
.SS Level
|
|
Base or Interrupt.
|
|
.SS "Synchronization Constraints"
|
|
Driver-defined basic locks, read/write locks, and sleep locks
|
|
may be held across calls to this function.
|
|
.SH REFERENCES
|
|
.na
|
|
\f4itimeout\fP(D3),
|
|
\f4LOCK_ALLOC\fP(D3),
|
|
\f4untimeout\fP(D3)
|
|
.ad
|