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 Sep 16, 2016 15.Dt USBA_HCDI_DUP_ISOC_REQ 9F 16.Os 17.Sh NAME 18.Nm usba_hcdi_dup_isoc_req 19.Nd duplicate an isochronous request 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft "usb_isoc_req_t *" 23.Fo usba_hcdi_dup_isoc_req 24.Fa "dev_info_t *dip" 25.Fa "usb_isoc_req_t *usrp" 26.Fa "usb_flags_t flags" 27.Fc 28.Sh INTERFACE LEVEL 29.Sy Volatile - 30illumos USB HCD private function 31.Pp 32This is a private function that is not part of the stable DDI. 33It may be removed or changed at any time. 34.Sh PARAMETERS 35.Bl -tag -width Fa 36.It Fa dip 37A pointer to the HCD driver's 38.Sy dev_info 39structure. 40.It Fa usrp 41A pointer to the USB isochronous request which will be duplicated. 42.It Fa flags 43.Bl -tag -width Sy 44.It Sy USB_FLAGS_NOSLEEP 45Do not block waiting for memory. 46If memory is not available the allocation will fail. 47.It Sy USB_FLAGS_SLEEP 48Perform a blocking allocation. 49If memory is not available, the function will wait until memory is made 50available. 51.Pp 52Note, the request may still fail even if 53.Sy USB_FLAGS_SLEEP 54is specified. 55.El 56.El 57.Sh DESCRIPTION 58The 59.Fn usba_hcdi_dup_isoc_req 60function is used to duplicate an existing isochronous request, 61.Fa usrp . 62.Pp 63When the USBA framework initiates an isochronous in transfer with the 64.Xr usba_hcdi_pipe_isoc_xfer 9E 65entry point, it is the HCD driver's responsibility to receive the 66periodic data from the pipe. 67When there is data available, the HCD must duplicate the original isochronous 68request and copy the available data into the request structure's 69.Fa isoc_data 70member, before handing over the request structure to the USBA framework 71by calling the 72.Xr usba_hcdi_cb 9F 73function. 74.Pp 75In addition to duplicating the request, it is the callers responsibility 76to increase the pipe handle's request count. 77For more information, see 78.Xr usba_hcdi_pipe_isoc_xfer 9E . 79.Pp 80The 81.Fa dip 82argument should correspond to the HCD driver's 83.Sy dev_info_t 84structure. 85The 86.Fa usrp 87pointer should correspond to the initial isochronous request. 88The 89.Fa flags 90member must be appropriate for the context. 91If 92.Dv USB_FLAGS_SLEEP 93is passed while in interrupt context, then this function may fail. 94.Sh CONTEXT 95The 96.Fn usba_hcdi_dup_isoc_req 97function may be called from 98.Sy user , 99.Sy kernel , 100or 101.Sy interrupt 102context; however, when in interrupt context, the value of 103.Fa flags 104must be 105.Sy USB_FLAGS_NOSLEEP . 106.Sh RETURN VALUES 107Upon successful completion, the 108.Fn usba_hcdi_dup_isoc_req 109function returns a pointer to a duplicate isochronous request. 110Otherwise, 111.Sy NULL 112is returned to indicate that the request could not be duplicated. 113.Sh SEE ALSO 114.Xr usba_hcdi 9E , 115.Xr usba_hcdi_pipe_isoc_xfer 9E , 116.Xr usba_hcdi_cb 9F 117