io_select(3K) DG/UX 5.4R3.00 io_select(3K)
NAME
ioselect: ioselectcancel, ioselectinit, ioselectregister,
ioselectsatisfy - access device select lists
SYNOPSIS
#include "/usr/src/uts/aviion/ii/iio.h"
ioselectintenttype ioselectcancel (selectlistptr, ecptr)
ioselectlistptrtype selectlistptr; /*WRITE ONLY*/
vpecptrtype ecptr; /*READ ONLY*/
void ioselectinit (selectlistptr)
ioselectlistptrtype selectlistptr; /*WRITE ONLY*/
void ioselectregister (selectlistptr, intent, ecptr)
ioselectlistptrtype selectlistptr; /*READ/WRITE*/
ioselectintenttype intent; /*READ ONLY*/
vpecptrtype ecptr; /*READ ONLY*/
void ioselectsatisfy (selectlistptr, intent)
ioselectlistptrtype selectlistptr; /*WRITE ONLY*/
ioselectintenttype intent; /*READ ONLY*/
where:
ecptr A pointer to a process's select eventcounter.
intent The type of select to satisfy.
selectlistptr A pointer to a select list.
DESCRIPTION
The following routines are described in this man page:
ioselectcancel Remove process from the select list
ioselectinit Initialize a select list
ioselectregister Register a select operation for a given select
list
ioselectsatisfy Search select list for processes interested in
given I/O event
Select is effectively a way of synchronizing user processes with
asynchronous driver activity. Since such synchronization is an
intrinsic part of the STREAMS facility, the select routines described
here are not appropriate to STREAMS drivers and modules. This man
page contains routines used by a select routine for a standard DG/UX
driver. Throughout the man page we refer to the driver's select
routine as the devxxxselect routine.
Overview to Using the Select Manager Routines
The select manager facility consists of a set of utility routines
that a driver may use to help implement its devxxxselect routine.
Select operations allow a user to wait for multiple I/O requests from
a device without directly suspending. The kernel's select routines
help your driver manage select operations by maintaining lists of
outstanding select operations for each device. Note that some
devices (for example, disks) always return TRUE when selected because
the operations complete quickly and cannot be interrupted. Drivers
Licensed material--property of copyright holder(s) 1
io_select(3K) DG/UX 5.4R3.00 io_select(3K)
for such devices will not need the routines in this man page because
their select operations do not need to keep lists of waiting users.
The select manager keeps a list of the processes waiting for I/O
events on a particular device. To use the select manager routines,
during initialization you must allocate a data structure of type
ioselectlisttype for each physical device that may be selected.
This structure is the head of the select-request list and holds
information the select manager needs to handle the list. You must
initialize each select list by calling ioselectinit before the list
is used.
When a user makes a select request, the kernel passes control to the
driver's devxxxselect routine. If the select condition is
satisfied, devxxxselect will return TRUE immediately. If the
select condition is not satisfied, devxxxselect can place an entry
on the device's select list by calling ioselectregister. The entry
records the intent of the select: read, write, or exception. It also
contains a pointer to the eventcounter to be raised when the select
condition is satisfied.
When an I/O event occurs on the device (for example, the driver
receives data, learns the device is ready for writing, or discovers
an exceptional condition on a device), the driver calls
ioselectsatisfy with the corresponding intent
(read/write/exception) flagged. Ioselectsatisfy traverses the
device's select list to advance the eventcounters and hence wake up
the processes interested in that event.
Note that ioselectsatisfy leaves the entry on the select list
whether it is satisfied or not. To remove the entry devxxxselect
calls ioselectcancel. Until it is canceled the entry's
eventcounter will continue to advance when the indicated select
condition is satisfied. Every ioselectregister must eventually be
followed by a call to ioselectcancel so old entries are not left on
the list.
CAUTION: It is essential that you note the following items:
The select manager operations do NOT lock the select-
request lists. The device driver must lock the list
structure to ensure that accesses to the select list are
single-threaded or ensure that at most one of the select
manager functions is in progress on a particular select
list at one time. If, for example, ioselectregister is
trying to add a new entry to the select list at the same
time ioselectsatisfy is trying to traverse the list,
indeterminate results may occur, possibly even a kernel
panic.
Ioselectsatisfy will frequently be called from an
interrupt service routine. If you call it from a service
routine, be sure to mask out the device's interrupts before
you call other routines with its select list. If you
Licensed material--property of copyright holder(s) 2
io_select(3K) DG/UX 5.4R3.00 io_select(3K)
don't, the interrupt level may encounter a partially
processed list.
Constants and Data Structures
This subsection describes constants and data structures defined in
the include files cited in the SYNOPSIS section and used by the
routines documented in this man page.
Try to avoid dependencies on the specifics of these structures, such
as size or location of fields, because these specifics may change in
later releases of the software. You can verify exact variable
definitions in the appropriate include file. The best way to avoid
such dependencies is to use kernel-supplied routines to manipulate
these structures.
ioselectintenttype
typedef bit16type ioselectintenttype ;
IOSELECTINTENTREAD
IOSELECTINTENTWRITE
IOSELECTINTENTEXCEPTION
IOSELECTINTENTNONE
This type describes the select options that may be specified to a
device driver's devxxxselect routine. The READ, WRITE, and
EXCEPTION options start a select for the corresponding operation.
You can use any combination of these three options in a single
devxxxselect call. IO_SELECT_INTENT_NONE is used as a return value
from ioselectcancel when no intent has been satisfied.
ioselectcancel
This routine removes the process identified by ecptr from the select
list.
ioselectinit
This routine initializes the given select list.
ioselectregister
This routine registers a select with the given intent and
eventcounter on the given select list.
See the "Constants and Data Structures" subsection for a list of
defines for intent.
ioselectsatisfy
This routine searches the given select list for processes interested
in the given I/O event. The select eventcounters for those processes
are advanced.
DIAGNOSTICS
Return Value
For ioselectcancel:
intent The type of select intent satisfied (or none).
For the other routines: none.
Licensed material--property of copyright holder(s) 3
io_select(3K) DG/UX 5.4R3.00 io_select(3K)
Errors
None.
SEE ALSO
devicedriver(3K), eventcounters(3K).
Programming in the DG/UX Kernel Environment.
Licensed material--property of copyright holder(s) 4