Tribblix: manual page: usba_pipe_handle

USBA_PIPE_HANDLE_DATA(9S) Data Structures for Drivers

NAME

usba_pipe_handle_data, usba_pipe_handle_data_t - USBA Pipe Handle Data
Structure

SYNOPSIS

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

INTERFACE LEVEL

Volatile - illumos USB HCD private

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

DESCRIPTION

The usba_pipe_handle_data structure is the USB architecture's (USBA)
way of representing a pipe. Every pipe is a part of a USB device.
Pipe's may be shared between client drivers or be exclusive to one.
For more background on pipe's see the USB Endpoint Background section
of usba_hcdi(9E).

This structure is provided to HCD driver's when performing requests of
various kinds. The majority of the structures listed here are
read-only; however, HCD drivers are allowed to update a single member,
listed below. All of the writable members are protected by a lock, the
member p_mutex. See the Locking section in usba_hcdi(9E) for more
information on lock ordering and when HCD drivers should enter this
lock.

A pipe handle has an explicit life cycle wih a device driver. The
driver first sees the pipe handle when its usba_hcdi_pipe_open(9E)
entry point is called. At that time, the HCD driver has the change to
store private data on the handle. This pipe handle will be used in
subsequent requests until the handle is closed, through a call to the
HCD driver's usba_hcdi_pipe_close(9E) entry point.

STRUCTURE MEMBERS

The usba_pipe_handle_data_t structure includes the following members:

usba_device_t *p_usba_device;
usb_ep_descr_t p_ep;
usb_ep_xdescr_t p_xep;
dev_info_t p_dip;
usb_opaque_t p_hcd_private;
kmutex_t p_mutex;
int p_req_count;

The p_usba_device member points to the usba_device(9S) structure that
this pipe belongs to. This member should always be set for an endpoint
handed to an HCD driver.

The p_ep member is filled in with the endpoint descriptor that
represents this device. The endpoint structure is documented in
usb_ep_descr(9S).

The p_xep member is filled in with the endpoint descriptor and any
additional endpoint descriptors that may exist. The structure is
documented in usb_ep_xdescr(9S). The endpoint descriptor is the same
in both p_ep and p_xep.

The p_hcd_private member is reserved for use with HCD drivers. An HCD
driver may set this member during usba_hcdi_pipe_open(9E). If set, it
can reference this member throughout the life time of the pipe. The
driver should ensure to clean it up when its usba_hcdi_pipe_close(9E)
entry point is called.

The p_mutex member protects the member p_req_count. The mutex should
be entered whenever the value is being manipulated.

The p_req_count member indicates the number of outstanding requests on
the pipe. When performing periodic interrupt or isochronous transfers,
it is the responsibility of the HCD driver to increment the value of
p_req_count if it duplicates a request with either
usba_hcdi_dup_intr_req(9F) or usba_hcdi_dup_isoc_req(9F).

Similarly, if the device driver for some reasons removes a request it
duplicated without submitting it to the USBA, it should decrement the
member.

The HCD driver should take special care to ensure that the value of
p_req_count is always greater than one. There should always be an
outstanding request that an HCD driver has for the pipe, especially if
it is a periodic endpoint. It should only manipulate this member while
it owns p_mutex.

NAME

SYNOPSIS

INTERFACE LEVEL

DESCRIPTION

STRUCTURE MEMBERS

SEE ALSO