|USBA_HCDI_PIPE_OPEN(9E)||Driver Entry Points||USBA_HCDI_PIPE_OPEN(9E)|
*ph, usb_flags_t usb_flags);
*ph, usb_flags_t usb_flags);
This is a private function that is not part of the stable DDI. It may be removed or changed at any time.
Note, the request may still fail even if USB_FLAGS_SLEEP is specified.
usba_hcdi_pipe_close() entry points are called by the USB framework whenever a client, or the framework itself, need to open or close a specific pipe. For additional background see usba_hcdi(9E).
When a pipe is opened, the host controller driver is responsible for preparing the specified endpoint for performing transfers. This may include allocating bandwidth, programming the controller, and more. When the pipe is closed, the host controller driver is responsible for cleaning up any resources that were allocated during the open call.
The pipe handle, ph, identifies the endpoint that it the USBA is trying to open or close through its endpoint descriptor in the p_ep member. The endpoint descriptor is described in usb_ep_descr(9S). From the endpoint descriptor the driver can determine the type of endpoint, what the address of the endpoint is, and what direction the endpoint is in. When combined, these uniquely describe the pipe.
To open a pipe, the driver may need additional companion endpoint descriptors. If these are available, they will be in the p_xep member of the pipe handle. See usb_ep_xdescr(9S) for more information on how to determine which descriptors are present and get the information encoded in them.
Host controller drivers should check the USB address of the USB device that ph belongs to. The driver may be asked to open a pipe to the root hub. As the root hub is often synthetic, the driver may need to take a different path than normal.
By the time the call to open a pipe returns, the driver should expect that any of the pipe transfer or reset entry points will be called on the pipe.
A driver can establish private data on an endpoint. During pipe open it may set the p_hcd_private member to any value. Generally this points to an allocated structure that contains data specific to the host controller. This value will remain on the pipe handle. It is the responsibility of the driver to clear the data when the pipe is closed.
For pipes that have outstanding periodic transfers, the host controller driver needs to clean them up and quiesce them as though a call to either usba_hcdi_pipe_stop_intr_polling(9E) or usba_hcdi_pipe_stop_isoc_polling(9E) had been called.
Just as with opening the pipe, the driver should pay attention to the address of the USB device, as it may be the root hub, which may be a synthetic pipe.
When a call to
completes, the device should be in a state that the pipe can be opened
uba_hcdi_pipe_close() functions should return USB_SUCCESS. Otherwise, it should return the appropriate USB error. If uncertain, use USB_FAILURE.
|February 15, 2020||illumos|