Tribblix: manual page: usba_hcdi_pipe

USBA_HCDI_PIPE_OPEN(9E) Driver Entry Points USBA_HCDI_PIPE_OPEN(9E)

NAME

usba_hcdi_pipe_open, usba_hcdi_pipe_close - open and close a USB pipe

SYNOPSIS

#include <sys/usb/usba/hcdi.h>

int
prefix_hcdi_pipe_open(usba_pipe_handle_data_t *ph,
usb_flags_t usb_flags);

int
prefix_hcdi_pipe_close(usba_pipe_handle_data_t *ph,
usb_flags_t usb_flags);

INTERFACE LEVEL

Volatile - illumos USB HCD private function

This is a private function that is not part of the stable DDI. It may
be removed or changed at any time.

PARAMETERS

ph A pointer to a USB pipe handle as defined in
usba_pipe_handle_data(9S).

usb_flags Flags which describe how allocations should be performed.
Valid flags are:

USB_FLAGS_NOSLEEP
Do not block waiting for memory. If memory is
not available the allocation will fail.

USB_FLAGS_SLEEP
Perform a blocking allocation. If memory is not
available, the function will wait until memory is
made available.

Note, the request may still fail even if
USB_FLAGS_SLEEP is specified.

DESCRIPTION

The usba_hcdi_pipe_open() and 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.

Pipe open specifics

A given endpoint on a device can only be opened once. If there's a
request to open an already open endpoint, then the request to open the
pipe should be failed.

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.

Pipe close specifics

When a pipe is closed, the driver must clean up all of the resources
that it allocated when opening the pipe. For non-periodic transfers,
the host controller driver may assume that there are no outstanding
transfers that need to be cleaned up. However, the same is not true
for periodic pipes.

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 usba_hcdi_pipe_close() completes, the device should be
in a state that the pipe can be opened again.

RETURN VALUES

Upon successful completion, the usba_hcdi_pipe_open() and
uba_hcdi_pipe_close() functions should return USB_SUCCESS. Otherwise,
it should return the appropriate USB error. If uncertain, use
USB_FAILURE.