PSARC/2008/628 Interrupt Resource Management

[David Kahn]

Scott,

The problem with the description of the nreq parameter
in the man page is that it doesn't say what it is
in that function call. I don't know what it means
that it's "initially set to be equal ...". That
isn't how we specify an interface.

You might want to replace DESCRIPTION section
with something like this: (basically replacing
your 2nd paragraph with 2 new paragraphs.)

   The ddi_intr_set_nreq() function changes the number of
   interrupts requested by a device driver instance.

   The nreq parameter is the total number of interrupt
   resources that this instance of the device driver
   would like to have available. nreq includes any
   interrupt resources already allocated by the driver.

   For example, the driver instance is currently using
   two MSI-X vectors, and it wants access to four additional
   unique MSI-X vectors. In that case it should call
   this function with nreq parameter set to the value six.

     The nreq parameter can be any value between 1 and the maximum
     number of interrupts supported by the device hardware, as reported
     by a call to the ddi_intr_get_nintrs(9F) function.  The driver will
     receive a callback notifying it in cases when it must release any
     previously allocated interrupts, or when it is allowed to allocate
     more interrupts as a result of its new nreq parameter.

     The ddi_intr_set_nreq() function is not supported unless a driver
     is already consuming interrupts, and if it has a registered callback
     handler that can process actions related to changes in interrupt
     availability.  See ddi_cb_register(9F) for an explanation on how
     to enable this functionality.


(and this part might go into an implementation note section,
because it's not part of the interface, but describes how the
interface is implemented.)

   The implementation tracks the number of interrupt
   resources that a device driver instance wants by
   initially using the ....

   As the driver processes more data streams and i/o load,
   it may decide that
   it wants more interrupt resources later. As that
   data and i/o load diminishes, it may decide that
   it has extra interrupt resources that can be returned
   to the system for use by other devices. ...




Here's what's there now:

DESCRIPTION
     The ddi_intr_set_nreq() function changes the number of interrupts
     requested by a device driver.

     The nreq parameter is initially set to be equal to the count
     parameter when the device driver first calls the ddi_intr_alloc(9F)
     function.  If the device driver detects changes in its workload,
     and it decides it needs more or less interrupt vectors, then it
     may use the ddi_intr_set_nreq() function to adjust its nreq
     parameter at arbitrary times.

     The nreq parameter can be any value between 1 and the maximum
     number of interrupts supported by the device hardware, as reported
     by a call to the ddi_intr_get_nintrs(9F) function.  The driver will
     receive a callback notifying it in cases when it must release any
     previously allocated interrupts, or when it is allowed to allocate
     more interrupts as a result of its new nreq parameter.

     The ddi_intr_set_nreq() function is not supported unless a driver
     is already consuming interrupts, and if it has a registered callback
     handler that can process actions related to changes in interrupt
     availability.  See ddi_cb_register(9F) for an explanation on how
     to enable this functionality.