1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2016 Joyent, Inc. 13.\" 14.Dd Dec 20, 2016 15.Dt USBA_PIPE_HANDLE_DATA 9S 16.Os 17.Sh NAME 18.Nm usba_pipe_handle_data , 19.Nm usba_pipe_handle_data_t 20.Nd USBA Pipe Handle Data Structure 21.Sh SYNOPSIS 22.In sys/usb/usba/hcdi.h 23.Sh INTERFACE LEVEL 24.Sy Volatile - 25illumos USB HCD private 26.Pp 27This is a private data structure that is not part of the stable DDI. 28It may be removed or changed at any time. 29.Sh DESCRIPTION 30The 31.Sy usba_pipe_handle_data 32structure is the USB architecture's (USBA) way of representing a pipe. 33Every pipe is a part of a USB device. 34Pipe's may be shared between client drivers or be exclusive to one. 35For more background on pipe's see the 36.Sy USB Endpoint Background 37section of 38.Xr usba_hcdi 9E . 39.Pp 40This structure is provided to HCD driver's when performing requests of 41various kinds. 42The majority of the structures listed here are 43.Em read-only ; 44however, HCD drivers are allowed to update a single member, listed 45below. 46All of the writable members are protected by a lock, the member 47.Sy p_mutex . 48See the 49.Sy Locking 50section in 51.Xr usba_hcdi 9E 52for more information on lock ordering and when HCD drivers should enter 53this lock. 54.Pp 55A pipe handle has an explicit life cycle wih a device driver. 56The driver first sees the pipe handle when its 57.Xr usba_hcdi_pipe_open 9E 58entry point is called. 59At that time, the HCD driver has the change to store private data on the handle. 60This pipe handle will be used in subsequent requests until the handle is closed, 61through a call to the HCD driver's 62.Xr usba_hcdi_pipe_close 9E 63entry point. 64.Sh STRUCTURE MEMBERS 65The 66.Sy usba_pipe_handle_data_t 67structure includes the following members: 68.Bd -literal -offset -indent 69usba_device_t *p_usba_device; 70usb_ep_descr_t p_ep; 71usb_ep_xdescr_t p_xep; 72dev_info_t p_dip; 73usb_opaque_t p_hcd_private; 74kmutex_t p_mutex; 75int p_req_count; 76.Ed 77.Pp 78The 79.Sy p_usba_device 80member points to the 81.Xr usba_device 9S 82structure that this pipe belongs to. 83This member should always be set for an endpoint handed to an HCD driver. 84.Pp 85The 86.Sy p_ep 87member is filled in with the endpoint descriptor that represents this 88device. 89The endpoint structure is documented in 90.Xr usb_ep_descr 9S . 91.Pp 92The 93.Sy p_xep 94member is filled in with the endpoint descriptor and any additional 95endpoint descriptors that may exist. 96The structure is documented in 97.Xr usb_ep_xdescr 9S . 98The endpoint descriptor is the same in both 99.Sy p_ep 100and 101.Sy p_xep . 102.Pp 103The 104.Sy p_hcd_private 105member is reserved for use with HCD drivers. 106An HCD driver may set this member during 107.Xr usba_hcdi_pipe_open 9E . 108If set, it can reference this member throughout the life time of the 109pipe. 110The driver should ensure to clean it up when its 111.Xr usba_hcdi_pipe_close 9E 112entry point is called. 113.Pp 114The 115.Sy p_mutex 116member protects the member 117.Sy p_req_count . 118The mutex should be entered whenever the value is being manipulated. 119.Pp 120The 121.Sy p_req_count 122member indicates the number of outstanding requests on the pipe. 123When performing 124.Em periodic 125interrupt or isochronous transfers, it is the responsibility of the HCD 126driver to increment the value of 127.Sy p_req_count 128if it duplicates a request with either 129.Xr usba_hcdi_dup_intr_req 9F 130or 131.Xr usba_hcdi_dup_isoc_req 9F . 132.Pp 133Similarly, if the device driver for some reasons removes a request it 134duplicated without submitting it to the USBA, it should decrement the 135member. 136.Pp 137The HCD driver should take special care to ensure that the value of 138.Sy p_req_count 139is always greater than one. 140There should always be an outstanding request that an HCD driver has for the 141pipe, especially if it is a periodic endpoint. 142It should only manipulate this member while it owns 143.Sy p_mutex . 144.Sh SEE ALSO 145.Xr usba_hcdi_pipe_close 9E , 146.Xr usba_hcdi_pipe_open 9E , 147.Xr usba_hcdi_dup_intr_req 9F , 148.Xr usba_hcdi_dup_isoc_req 9F , 149.Xr usb_ep_descr 9S , 150.Xr usb_ep_xdescr 9S , 151.Xr usba_device 9S 152