chpoll(D2) chpoll(D2)
NAME
chpoll - poll entry point for a non-STREAMS character driver
SYNOPSIS
#include <sys/poll.h>
#include <sys/ddi.h>
int prefixchpoll(dev_t dev, short events, int anyyet, short *reventsp,
struct pollhead **phpp);
Arguments
dev The device number for the device to be polled.
events Mask (bit-wise OR) indicating the events being
polled.
anyyet A flag that indicates whether the driver should
return a pointer to its pollhead structure to the
caller.
reventsp A pointer to a bitmask of the returned events
satisfied.
phpp A pointer to a pointer to a pollhead structure
(defined in sys/poll.h).
DESCRIPTION
The chpoll entry point indicates whether certain I/O events
have occurred on a given device. It must be provided by any
non-STREAMS character device driver that wishes to support
polling [see poll(2)].
Return Values
The chpoll routine should return 0 for success, or the
appropriate error number.
USAGE
This entry point is optional, and is valid for character
device drivers only.
Valid values for events are:
POLLIN Data is available to be read (either
normal or out-of-band).
Copyright 1994 Novell, Inc. Page 1
chpoll(D2) chpoll(D2)
POLLOUT Data may be written without blocking.
POLLPRI High priority data are available to be
read.
POLLHUP A device hangup.
POLLERR A device error.
POLLRDNORM Normal data is available to be read.
POLLWRNORM Normal data may be written without
blocking (same as POLLOUT).
POLLRDBAND Out-of-band data is available to be read.
POLLWRBAND Out-of-band data may be written without
blocking.
A driver that supports polling must provide a pollhead
structure for each minor device supported by the driver. On
systems where they are available, the driver should use the
phalloc(D3) function to allocate the pollhead structure, and
use the phfree(D3) function to free the pollhead structure, if
necessary.
The pollhead structure must be initialized to zeros prior to
its first use (when phalloc is used to allocate the structure,
this is done automatically).
The definition of the pollhead structure is not included in
the DDI/DKI, and can change across releases. It should be
treated as a ``black box'' by the driver; none of its fields
may be referenced. Although the size of the pollhead
structure is guaranteed to remain the same across releases, it
is good practice for drivers not to depend on the size of the
structure.
The driver must implement the polling discipline itself. Each
time the driver detects a pollable event, it should call
pollwakeup(D3), passing to it the event that occurred and the
address of the pollhead structure associated with the device.
Note that pollwakeup should be called with only one event at a
time.
Copyright 1994 Novell, Inc. Page 2
chpoll(D2) chpoll(D2)
When the driver's chpoll entry point is called, the driver
should check if any of the events requested in events have
occurred. The driver should store the mask, consisting of the
subset of events that are pending, in the short pointed to by
reventsp. Note that this mask may be 0 if none of the events
are pending. In this case, the driver should check the anyyet
flag and, if it is zero, store the address of the device's
pollhead structure in the pointer pointed at by phpp. The
canonical chpoll algorithm is:
if (events_are_satisfied_now) {
*reventsp = events & mask_of_satisfied_events;
} else {
*reventsp = 0;
if (!anyyet)
*phpp = my_local_pollhead_pointer;
}
return (0);
Synchronization Constraints
On uniprocessor systems, user context is available in the
chpoll routine, but if the driver sleeps, it must do so such
that signals do not cause the sleep to longjmp [see
sleep(D3)].
On multiprocessor systems, the chpoll routine may not call any
function that sleeps.
REFERENCES
bzero(D3), phalloc(D3), phfree(D3), poll(2), pollwakeup(D3)
NOTICES
Portability
All processors
Applicability
ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp
Copyright 1994 Novell, Inc. Page 3