Kernel Functions for Drivers              usbpipedrainreqs(9F)



NAME
     usbpipedrainreqs  -  Allow  completion  of  pending  pipe
     requests

SYNOPSIS
     #include 



     int usbpipedrainreqs(devinfot *dip, usbpipehandlet pipehandle,
          uintt timeout, usbflagst usbflags,
          void (*callback)(usbpipehandlet pipehandle,
          usbopaquet callbackarg, int rval, usbcbflagst flags),
          usbopaquet callbackarg);


INTERFACE LEVEL
     Solaris DI specific (Solaris DI)

PARAMETERS
     dip             Pointer to the device's devinfo structure.


     pipehandle     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           USBFLAGSLEP is the only flag recognized.
                     Wait  for  completion  and do not call call-
                     back.


     callback        Callback handler to notify  of  asynchronous
                     completion.


     callbackarg    Second argument passed to callback function.


DESCRIPTION
     The usbpipedrainreqs() 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 pipehandle 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



SunOS 5.11           Last change: 5 Jan 2004                    1






Kernel Functions for Drivers              usbpipedrainreqs(9F)



     that  pipe  that  are  associated  with a given dip are com-
     pleted.


     The usbpipedrainreqs() 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
     usbpipeclose(9F) allows all requests in a pipe  to  finish
     before  returning. However, a client driver cannot close the
     default control pipe.


     If USBFLAGSLEP 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:

     usbpipehandlet defaultpipehandle

         Handle of the pipe to drain.


     usbopaquet callbackarg

         callbackarg specified to usbpipedrainreqs().


     int rval

         Request status.


     usbcbflagst callbackflags

         Status of the queueing operation. Can be:

         USBCBNOINFO             Callback was uneventful.


         USBCBASYNCREQFAILED    Error  starting  asynchronous
                                    request.



RETURN VALUES
     USBSUCES            Request is successful.




SunOS 5.11           Last change: 5 Jan 2004                    2






Kernel Functions for Drivers              usbpipedrainreqs(9F)



     USBINVALIDARGS       dip argument is NUL. USBFLAGSLEP
                            is clear and callback is NUL.


     USBINVALIDCONTEXT    Called from callback context with the
                            USBFLAGSLEP flag set.


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


CONTEXT
     May be called from user or kernel context.


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

EXAMPLES
         mydevdetach(devinfot *dip, ddidetachcmdt cmd)
        {

             ...
             ...

             mydevstate->pipestate = CLOSED;

             /* Wait for pending requests of a pipe to finish.  Don't timeout. */
             (void) usbpipedrainreqs(
                 dip, pipehandle, 0, USBFLAGSLEP, NUL, 0);

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



NOTES
     For pipes other than the default control pipe, it is  recom-
     mended    to    close   the   pipe   using   a   synchronous



SunOS 5.11           Last change: 5 Jan 2004                    3






Kernel Functions for Drivers              usbpipedrainreqs(9F)



     usbpipeclose(). usbpipeclose() with the  USBFLAGSLEP
     flag  allows  any  pending requests in that pipe to complete
     before returning.


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

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



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     Architecture                 PCI-based systems           
    
     Interface stability          Committed                   
    
     Availability                 SUNWusb                     
    


SEE ALSO
     attributes(5),    usbpipeclose(9F),    usbpipereset(9F),
     usbcallbackflags(9S)

























SunOS 5.11           Last change: 5 Jan 2004                    4