Manual Pages for UNIX Operating System command usage for man usb_pipe_drain_reqs

Kernel Functions for Drivers              usb_pipe_drain_reqs(9F)



NAME
     usb_pipe_drain_reqs  -  Allow  completion  of  pending  pipe
     requests

SYNOPSIS
     #include 

     int usb_pipe_drain_reqs(dev_info_t *dip, usb_pipe_handle_t pipe_handle,
          uint_t timeout, usb_flags_t usb_flags,
          void (*callback)(usb_pipe_handle_t pipe_handle,
          usb_opaque_t callback_arg, int rval, usb_cb_flags_t flags),
          usb_opaque_t callback_arg);


INTERFACE LEVEL
     Solaris DDI specific (Solaris DDI)

PARAMETERS
     dip             Pointer to the device's dev_info structure.


     pipe_handle     Handle  of  the  pipe   containing   pending
                     requests.


     timeout         Maximum wait time  for  requests  to  drain.
                     Must  be  a  non-negative  value in seconds.
                     Zero specifies no timeout.


     flags           USB_FLAGS_SLEEP is the only flag recognized.
                     Wait  for  completion  and do not call call-
                     back.


     callback        Callback handler to notify  of  asynchronous
                     completion.


     callback_arg    Second argument passed to callback function.


DESCRIPTION
     The usb_pipe_drain_reqs() function provides waits for  pend-
     ing  requests  to  complete and then provides synchronous or
     asynchronous notification that all  pending  requests  on  a
     non-shared pipe indicated by pipe_handle have completed. For
     a shared pipe (such as the default control pipe used by mul-
     tiple drivers each managing one interface of a device), this
     function provides notification that all pending requests  on
     that  pipe  that  are  associated  with a given dip are com-
     pleted.



SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers              usb_pipe_drain_reqs(9F)



     The usb_pipe_drain_reqs() function can be used to  notify  a
     close  procedure when the default control pipe is clear dur-
     ing device closure, thereby allowing the close procedure  to
     continue   safely.   Normally,   a   synchronous   call   to
     usb_pipe_close(9F) allows all requests in a pipe  to  finish
     before  returning. However, a client driver cannot close the
     default control pipe.


     If USB_FLAGS_SLEEP is set in flags, block until all  pending
     requests  are  completed.  Otherwise, return immediately and
     call the callback handler when all pending requests are com-
     pleted.


     The callback parameter  accepts  the  asynchronous  callback
     handler, which takes the following arguments:

     usb_pipe_handle_t default_pipe_handle

         Handle of the pipe to drain.


     usb_opaque_t callback_arg

         callback_arg specified to usb_pipe_drain_reqs().


     int rval

         Request status.


     usb_cb_flags_t callback_flags

         Status of the queueing operation. Can be:

         USB_CB_NO_INFO             Callback was uneventful.


         USB_CB_ASYNC_REQ_FAILED    Error  starting  asynchronous
                                    request.



RETURN VALUES
     USB_SUCCESS            Request is successful.


     USB_INVALID_ARGS       dip argument is NULL. USB_FLAGS_SLEEP
                            is clear and callback is NULL.




SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers              usb_pipe_drain_reqs(9F)



     USB_INVALID_CONTEXT    Called from callback context with the
                            USB_FLAGS_SLEEP flag set.


     USB_INVALID_PIPE       Pipe is not open, is  closing  or  is
                            closed.


CONTEXT
     May be called from user or kernel context.


     If   the   USB_CB_ASYNC_REQ_FAILED   bit   is    clear    in
     usb_cb_flags_t, the callback, if supplied, can block because
     it is executing in kernel context.  Otherwise  the  callback
     cannot  block.  Please  see  usb_callback_flags(9S) for more
     information on callbacks.

EXAMPLES
         mydev_detach(dev_info_t *dip, ddi_detach_cmd_t cmd)
        {

             ...
             ...

             mydev_state->pipe_state = CLOSED;

             /* Wait for pending requests of a pipe to finish.  Don't timeout. */
             (void) usb_pipe_drain_reqs(
                 dip, pipe_handle, 0, USB_FLAGS_SLEEP, NULL, 0);

             /*
              * Dismantle streams and tear down this instance,
              * now that all requests have been sent.
              */
             qprocsoff(q);
             ...
             ...
             ddi_remove_minor_node(dip, NULL);
             ...
             ...
        }



NOTES
     For pipes other than the default control pipe, it is  recom-
     mended    to    close   the   pipe   using   a   synchronous
     usb_pipe_close(). usb_pipe_close() with the  USB_FLAGS_SLEEP
     flag  allows  any  pending requests in that pipe to complete
     before returning.




SunOS 5.11           Last change: 5 Jan 2004                    3






Kernel Functions for Drivers              usb_pipe_drain_reqs(9F)



     Do not call usb_pipe_drain_reqs() while additional  requests
     are  being  submitted by a different thread. This action can
     stall the calling thread of  usb_pipe_drain_reqs()  unneces-
     sarily.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | PCI-based systems           |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | Availability                | driver/usb                  |
    |_____________________________|_____________________________|


SEE ALSO
     attributes(5),    usb_pipe_close(9F),    usb_pipe_reset(9F),
     usb_callback_flags(9S)






























SunOS 5.11           Last change: 5 Jan 2004                    4