illumos: manual page: usba_pipe_handle

USBA_PIPE_HANDLE_DATA(9S) Data Structures for Drivers USBA_PIPE_HANDLE_DATA(9S)

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