pollwakeup(D3)

NAME
     pollwakeup - inform polling processes that an event has occurred

SYNOPSIS
     #include <sys/poll.h>
     #include <sys/ddi.h>
     void pollwakeup(struct pollhead *php, short event);

   Arguments
     php       Pointer to a pollhead structure.

     event     Event to notify the process about.

DESCRIPTION
     The pollwakeup function provides non-STREAMS character drivers with a way
     to notify processes polling for the occurrence of an event.

   Return Values
     None

USAGE
     pollwakeup should be called from the driver for each occurrence of an
     event.  Events are described in poll(D2).

     The pollhead structure will usually be associated with the driver's
     private data structure for the particular minor device where the event
     has occurred.

     pollwakeup should only be called with one event at a time.

   Level
     Base or Interrupt.

   Synchronization Constraints
     Does not sleep.

     Driver-defined basic locks, read/write locks, and sleep locks may be held
     across calls to this function.

     Note that the portions of the driver which implement the driver's poll()
     routine and the lower layer which calls pollwakeup must agree on some
     fundamental synchronization between themselves.  Often this will be done
     via a lock to prevent the lower layer interrupt code and upper layer poll
     routine from manipulating state bits simultaneously or examining
     inconsistent state.  Of particular import is the poll() routine's
     snapshot of the driver's pollhead generation number (if the driver has a
     pollhead).  This snapshot must occur either within the inter-locked code
     in the poll() routine to hold off any call to pollwakeup in the lower
     layer, or it must be done before any event state is examined if there is
     no inter-lock between the high and low layers of the driver.  Of similar
     concern, the lower level layer must either call pollwakeup within an
     interlocked synchronization section or must call after all device state
     queried by the poll() routine has been updated.  See poll(D2) for an
     explanation of the race condition that is detected by this rule.

REFERENCES
     poll(2), poll(D2)