1 USBA_HCDI_PIPE_OPEN(9E)       Driver Entry Points      USBA_HCDI_PIPE_OPEN(9E)
   2 
   3 NAME
   4      usba_hcdi_pipe_open, usba_hcdi_pipe_close - open and close a USB pipe
   5 
   6 SYNOPSIS
   7      #include <sys/usb/usba/hcdi.h>
   8 
   9      int
  10      prefix_hcdi_pipe_open(usba_pipe_handle_data_t *ph,
  11          usb_flags_t usb_flags);
  12 
  13      int
  14      prefix_hcdi_pipe_close(usba_pipe_handle_data_t *ph,
  15          usb_flags_t usb_flags);
  16 
  17 INTERFACE LEVEL
  18      Volatile - illumos USB HCD private function
  19 
  20      This is a private function that is not part of the stable DDI.  It may be
  21      removed or changed at any time.
  22 
  23 PARAMETERS
  24      ph            A pointer to a USB pipe handle as defined in
  25                    usba_pipe_handle_data(9S).
  26 
  27      usb_flags     Flags which describe how allocations should be performed.
  28                    Valid flags are:
  29 
  30                    USB_FLAGS_NOSLEEP
  31                            Do not block waiting for memory.  If memory is not
  32                            available the allocation will fail.
  33 
  34                    USB_FLAGS_SLEEP
  35                            Perform a blocking allocation.  If memory is not
  36                            available, the function will wait until memory is
  37                            made available.
  38 
  39                            Note, the request may still fail even if
  40                            USB_FLAGS_SLEEP is specified.
  41 
  42 DESCRIPTION
  43      The usba_hcdi_pipe_open() and usba_hcdi_pipe_close() entry points are
  44      called by the USB framework whenever a client, or the framework itself,
  45      need to open or close a specific pipe.  For additional background see
  46      usba_hcdi(9E).
  47 
  48      When a pipe is opened, the host controller driver is responsible for
  49      preparing the specified endpoint for performing transfers.  This may
  50      include allocating bandwidth, programming the controller, and more.  When
  51      the pipe is closed, the host controller driver is responsible for
  52      cleaning up any resources that were allocated during the open call.
  53 
  54      The pipe handle, ph, identifies the endpoint that it the USBA is trying
  55      to open or close through its endpoint descriptor in the p_ep member.  The
  56      endpoint descriptor is described in usb_ep_descr(9S).  From the endpoint
  57      descriptor the driver can determine the type of endpoint, what the
  58      address of the endpoint is, and what direction the endpoint is in.  When
  59      combined, these uniquely describe the pipe.
  60 
  61      To open a pipe, the driver may need additional companion endpoint
  62      descriptors.  If these are available, they will be in the p_xep member of
  63      the pipe handle.  See usb_ep_xdescr(9S) for more information on how to
  64      determine which descriptors are present and get the information encoded
  65      in them.
  66 
  67      Host controller drivers should check the USB address of the USB device
  68      that ph belongs to.  The driver may be asked to open a pipe to the root
  69      hub.  As the root hub is often synthetic, the driver may need to take a
  70      different path than normal.
  71 
  72    Pipe open specifics
  73      A given endpoint on a device can only be opened once.  If there's a
  74      request to open an already open endpoint, then the request to open the
  75      pipe should be failed.
  76 
  77      By the time the call to open a pipe returns, the driver should expect
  78      that any of the pipe transfer or reset entry points will be called on the
  79      pipe.
  80 
  81      A driver can establish private data on an endpoint.  During pipe open it
  82      may set the p_hcd_private member to any value.  Generally this points to
  83      an allocated structure that contains data specific to the host
  84      controller.  This value will remain on the pipe handle.  It is the
  85      responsibility of the driver to clear the data when the pipe is closed.
  86 
  87    Pipe close specifics
  88      When a pipe is closed, the driver must clean up all of the resources that
  89      it allocated when opening the pipe.  For non-periodic transfers, the host
  90      controller driver may assume that there are no outstanding transfers that
  91      need to be cleaned up.  However, the same is not true for periodic pipes.
  92 
  93      For pipes that have outstanding periodic transfers, the host controller
  94      driver needs to clean them up and quiesce them as though a call to either
  95      usba_hcdi_pipe_stop_intr_polling(9E) or
  96      usba_hcdi_pipe_stop_isoc_polling(9E) had been called.
  97 
  98      Just as with opening the pipe, the driver should pay attention to the
  99      address of the USB device, as it may be the root hub, which may be a
 100      synthetic pipe.
 101 
 102      When a call to usba_hcdi_pipe_close() completes, the device should be in
 103      a state that the pipe can be opened again.
 104 
 105 RETURN VALUES
 106      Upon successful completion, the usba_hcdi_pipe_open() and
 107      uba_hcdi_pipe_close() functions should return USB_SUCCESS.  Otherwise, it
 108      should return the appropriate USB error.  If uncertain, use USB_FAILURE.
 109 
 110 SEE ALSO
 111      usba_hcdi(9E), usba_hcdi_pipe_stop_intr_polling(9E),
 112      usba_hcdi_pipe_stop_isoc_polling(9E), usb_ep_descr(9S),
 113      usb_ep_xdescr(9S), usba_pipe_handle_data(9S)
 114 
 115 illumos                        February 15, 2020                       illumos