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.

SEE ALSO

usba_hcdi_pipe_close(9E), usba_hcdi_pipe_open(9E), usba_hcdi_dup_intr_req(9F), usba_hcdi_dup_isoc_req(9F), usb_ep_descr(9S), usb_ep_xdescr(9S), usba_device(9S)