ddselect Device Driver Entry Point

Purpose

Checks to see if one or more events has occurred on the device.

Syntax

#include <sys/device.h>
#include <sys/poll.h>

int ddselect ( devno,  events,  reventp,  chan)
dev_t devno;
ushort events;
ushort *reventp;
int chan;

Parameters

Item Description
devno Specifies the major and minor device numbers.
events Specifies the events to be checked.
reventp Returned events pointer. This parameter, passed by reference, is used by the ddselect routine to indicate which of the selected events are true at the time of the call. The returned events location pointed to by the reventp parameter is set to 0 before entering this routine.
chan Specifies the channel number.

Description

The ddselect entry point is called when the select or poll subroutine is used, or when the fp_select kernel service is invoked. It determines whether a specified event or events have occurred on the device.

Only character class device drivers can provide the ddselect routine. It cannot be provided by block device drivers even when providing raw read/write access.

Requests for Information on Events

The events parameter represents possible events to check as flags (bits). There are three basic events defined for the select and poll subroutines, when applied to devices supporting select or poll operations:

Event Description
POLLIN Input is present on the device.
POLLOUT The device is capable of output.
POLLPRI An exceptional condition has occurred on the device.

A fourth event flag is used to indicate whether the ddselect routine should record this request for later notification of the event using the selnotify kernel service. This flag can be set in the events parameter if the device driver is not required to provide asynchronous notification of the requested events:

Event Description
POLLSYNC This request is a synchronous request only. The routine need not call the selnotify kernel service for this request even if the events later occur.

Additional event flags in the events parameter are left for device-specific events on the poll subroutine call.

Select Processing

If one or more events specified in the events parameter are true, the ddselect routine should indicate this by setting the corresponding bits in the reventp parameter. Note that the reventp returned events parameter is passed by reference.

If none of the requested events are true, then the ddselect routine sets the returned events parameter to 0. It is passed by reference through the reventp parameter. It also checks the POLLSYNC flag in the events parameter. If this flag is true, the ddselect routine should just return, since the event request was a synchronous request only.

However, if the POLLSYNC flag is false, the ddselect routine must notify the kernel when one or more of the specified events later happen. For this purpose, the routine should set separate internal flags for each event requested in the events parameter.

When any of these events become true, the device driver routine should use the selnotify service to notify the kernel. The corresponding internal flags should then be reset to prevent re-notification of the event.

Sometimes the device can be in a state in which a supported event or events can never be satisfied (such as when a communication line is not operational). In this case, the ddselect routine should simply set the corresponding reventp flags to 1. This prevents the select or poll subroutine from waiting indefinitely. As a result however, the caller will not in this case be able to distinguish between satisfied events and unsatisfiable ones. Only when a later request with an NDELAY option fails will the error be detected.

Note: Other device driver routines (such as the ddread, ddwrite routines) may require logic to support select or poll operations.

Execution Environment

The ddselect routine is executed only in the process environment. It should provide the required serialization of its data structures by using the locking kernel services in conjunction with a private lock word defined in the driver.

Return Values

The ddselect routine should return with a return code of 0 if the select or poll operation requested is valid for the resource specified. Requested operations are not valid, however, if either of the following is true:

In these cases, the ddselect routine should return with a nonzero return code (typically EINVAL), and without setting the relevant reventp flags to 1. This causes the poll subroutine to return to the caller with the POLLERR flag set in the returned events parameter associated with this resource. The select subroutine indicates to the caller that all requested events are true for this resource.

When applicable, the return values defined in the POSIX 1003.1 standard for the select subroutine should be used.