poll(D2)

NAME
     poll - poll entry point for a non-STREAMS character driver

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

   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 and the value of the
               pollhead's generation number 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).

     genp      A pointer to an unsigned integer that is used by the driver to
               store the current value of the pollhead's generation number at
               the time of the poll.

DESCRIPTION
     The poll 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 poll 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).

          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.

     When the driver's poll 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 and also store the
     value of the pollhead's generation number at the time of the poll in the
     unsigned integer pointed to by genp.

     The pollhead's generation value must be sampled either while a state lock
     is held that will hold off any call to pollwakeup(D3) on the pollhead by
     the lower portion of the driver, or it must be taken before the check is
     made for any pending events; pollwakeup(D3) increments the pollhead's
     generation number each time it is called.  The generation number is used
     to solve the race condition that exists for the caller of the poll()
     routine between the time that the driver's poll() routine is called and
     when the caller adds itself to the pollhead's waiter queue.  When the
     poll() routine is called, there may be no events of interest pending and
     the pollhead is returned by the driver poll() routine in order that the
     caller can queue itself onto the pollhead to wait for such events.  If
     the lower layer of the driver signals such an event via a call to
     pollwakeup(D3) before the caller can queue up, the caller may block
     forever or wait unnecessarily for the next such event before being woken
     up.  The snapshot of the pollhead's generation number at the time of the
     poll allows the caller to check the generation number of the pollhead as
     it is about to queue itself up.  If the snapshot value returned by the
     driver and the current generation number match, the caller can safely
     queue itself up.  If they don't match, the caller knows that it must
     retry the poll() operation since at least one call to pollwakeup(D3) must
     have occurred on the pollhead.

     The canonical poll() algorithm is:
     /* snapshot pollhead generation number before checking events */
     unsigned int gen = POLLGEN(my_local_pollhead_pointer);
     if (events_are_satisfied_now) {
          *reventsp = events & mask_of_satisfied_events;
     } else {
          *reventsp = 0;
          if (!anyyet) {
               *phpp = my_local_pollhead_pointer;
               *genp = gen;
          }
     }
     return (0);

   Synchronization Constraints
     On uniprocessor systems, user context is available in the poll routine,
     but if the driver sleeps, it must do so such that signals do not cause
     the sleep to longjump [see sleep(D3)].

     On multiprocessor systems, the poll routine may not call any function
     that sleeps.

REFERENCES
     bzero(D3), phalloc(D3), phfree(D3), poll(2), pollwakeup(D3), select(2)