SVR5

chpoll(D2)

chpoll -- poll entry point for a non-STREAMS character device driver

Synopsis (Not in current DDI version)

   #include <sys/poll.h>
   #include <sys/ddi.h>
   
   int prefixchpoll(dev_t dev, short events, int anyyet, short *reventsp,
   	struct pollhead **phpp);

Description

The driver's chpoll( ) entry point routine is called in non-STREAMS drivers to determine whether certain I/O events have occurred on a given device. This overrides the standard polling semantics used for regular files. The chpoll( ) routine is a named entry point and must be defined as a global symbol.

Arguments

dev: 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).

Return values

The chpoll routine should return 0 for success, or the appropriate error number from errnos(D5).

Usage

This entry point is optional, and is valid for non-STREAMS device drivers only. If this entry point is not provided, the polling behavior for the device is the same as for regular files. This entry point routine is called only when the device is open.

Valid values for events are:

POLLIN: Data is available to be read (either normal or out-of-band).
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. Use the phalloc(D3) function to allocate the pollhead structure, and use the phfree(D3) function to free the pollhead structure, if necessary. To drivers, the pollhead structure is an opaque object; none of its members can be referenced directly.

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.

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

Context and synchronization

Blockable context. The driver can block but cannot do operations such as copyout(D3) that require access to the requesting process's address space.

If the chpoll( ) entry point routine uses the sleep(D3) function to block, it must either sleep non-interruptible or use PCATCH.

Hardware applicability

All

Version applicability

ddi: 1, 2, 3, 4, 5, 5mp, 6, 6mp, 7, 7mp, 7.1, 7.1mp

External dependencies

Named entry point routines must be declared in the driver's Master(DSP/4dsp) file. The declaration for this entry point is $entry chpoll.

Differences between versions

Starting with DDI versions 8, the chpoll( ) entry point routine is not supported. There is no replacement.

The phalloc(D3) routine is not supported in DDI versions 1, 2, and 4 so pollhead structures must be allocated directly by the driver and must be initialized to zero before it is used with the bzero(D3) or kmem_zalloc(D3) routine or static allocation.

References

bzero(D3), phalloc(D3), phfree(D3), poll, pollwakeup(D3)