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. It 28may 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. Pipe's may be shared between 34client drivers or be exclusive to one. For more background on pipe's 35see 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. The majority of the structures listed here are 42.Em read-only ; 43however, HCD drivers are allowed to update a single member, listed 44below. All of the writable members are protected by a lock, the member 45.Sy p_mutex . 46See the 47.Sy Locking 48section in 49.Xr usba_hcdi 9E 50for more information on lock ordering and when HCD drivers should enter 51this lock. 52.Pp 53A pipe handle has an explicit life cycle wih a device driver. The driver 54first sees the pipe handle when its 55.Xr usba_hcdi_pipe_open 9E 56entry point is called. At that time, the HCD driver has the change to 57store private data on the handle. This pipe handle will be used in 58subsequent requests until the handle is closed, through a call to the 59HCD driver's 60.Xr usba_hcdi_pipe_close 9E 61entry point. 62.Sh STRUCTURE MEMBERS 63The 64.Sy usba_pipe_handle_data_t 65structure includes the following members: 66.Bd -literal -offset -indent 67usba_device_t *p_usba_device; 68usb_ep_descr_t p_ep; 69usb_ep_xdescr_t p_xep; 70dev_info_t p_dip; 71usb_opaque_t p_hcd_private; 72kmutex_t p_mutex; 73int p_req_count; 74.Ed 75.Pp 76The 77.Sy p_usba_device 78member points to the 79.Xr usba_device 9S 80structure that this pipe belongs to. This member should always be set 81for an endpoint handed to an HCD driver. 82.Pp 83The 84.Sy p_ep 85member is filled in with the endpoint descriptor that represents this 86device. The endpoint structure is documented in 87.Xr usb_ep_descr 9S . 88.Pp 89The 90.Sy p_xep 91member is filled in with the endpoint descriptor and any additional 92endpoint descriptors that may exist. The structure is documented in 93.Xr usb_ep_xdescr 9S . 94The endpoint descriptor is the same in both 95.Sy p_ep 96and 97.Sy p_xep . 98.Pp 99The 100.Sy p_hcd_private 101member is reserved for use with HCD drivers. An HCD driver may set 102this member during 103.Xr usba_hcdi_pipe_open 9E . 104If set, it can reference this member throughout the life time of the 105pipe. The driver should ensure to clean it up when its 106.Xr usba_hcdi_pipe_close 9E 107entry point is called. 108.Pp 109The 110.Sy p_mutex 111member protects the member 112.Sy p_req_count . 113The mutex should be entered whenever the value is being manipulated. 114.Pp 115The 116.Sy p_req_count 117member indicates the number of outstanding requests on the pipe. When 118performing 119.Em periodic 120interrupt or isochronous transfers, it is the responsibility of the HCD 121driver to increment the value of 122.Sy p_req_count 123if it duplicates a request with either 124.Xr usba_hcdi_dup_intr_req 9F 125or 126.Xr usba_hcdi_dup_isoc_req 9F . 127.Pp 128Similarly, if the device driver for some reasons removes a request it 129duplicated without submitting it to the USBA, it should decrement the 130member. 131.Pp 132The HCD driver should take special care to ensure that the value of 133.Sy p_req_count 134is always greater than one. There should always be an outstanding 135request that an HCD driver has for the pipe, especially if it is a 136periodic endpoint. It should only manipulate this member while it owns 137.Sy p_mutex . 138.Sh SEE ALSO 139.Xr usba_hcdi_pipe_close 9E , 140.Xr usba_hcdi_pipe_open 9E , 141.Xr usba_hcdi_dup_intr_req 9F , 142.Xr usba_hcdi_dup_isoc_req 9F , 143.Xr usb_ep_descr 9S , 144.Xr usb_ep_xdescr 9S , 145.Xr usba_device 9S 146