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. It may be 33removed 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. If memory is not available the allocation 46will fail. 47.It Sy USB_FLAGS_SLEEP 48Perform a blocking allocation. If memory is not available, the function 49will wait until memory is made available. 50.Pp 51Note, the request may still fail even if 52.Sy USB_FLAGS_SLEEP 53is specified. 54.El 55.El 56.Sh DESCRIPTION 57The 58.Fn usba_hcdi_dup_isoc_req 59function is used to duplicate an existing isochronous request, 60.Fa usrp . 61.Pp 62When the USBA framework initiates an isochronous in transfer with the 63.Xr usba_hcdi_pipe_isoc_xfer 9E 64entry point, it is the HCD driver's responsibility to receive the 65periodic data from the pipe. When there is data available, the HCD must 66duplicate the original isochronous request and copy the available data 67into the request structure's 68.Fa isoc_data 69member, before handing over the request structure to the USBA framework 70by calling the 71.Xr usba_hcdi_cb 9F 72function. 73.Pp 74In addition to duplicating the request, it is the callers responsibility 75to increase the pipe handle's request count. For more information, see 76.Xr usba_hcdi_pipe_isoc_xfer 9E . 77.Pp 78The 79.Fa dip 80argument should correspond to the HCD driver's 81.Sy dev_info_t 82structure. The 83.Fa usrp 84pointer should correspond to the initial isochronous request. The 85.Fa flags 86member must be appropriate for the context. If 87.Dv USB_FLAGS_SLEEP 88is passed while in interrupt context, then this function may fail. 89.Sh CONTEXT 90The 91.Fn usba_hcdi_dup_isoc_req 92function may be called from 93.Sy user , 94.Sy kernel , 95or 96.Sy interrupt 97context; however, when in interrupt context, the value of 98.Fa flags 99must be 100.Sy USB_FLAGS_NOSLEEP . 101.Sh RETURN VALUES 102Upon successful completion, the 103.Fn usba_hcdi_dup_isoc_req 104function returns a pointer to a duplicate isochronous request. 105Otherwise, 106.Sy NULL 107is returned to indicate that the request could not be duplicated. 108.Sh SEE ALSO 109.Xr usba_hcdi 9E , 110.Xr usba_hcdi_pipe_isoc_xfer 9E , 111.Xr usba_hcdi_cb 9F 112