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 May 10, 2016 15.Dt USBA_HCDI_DUP_INTER_REQ 9F 16.Os 17.Sh NAME 18.Nm usba_hcdi_dup_intr_req 19.Nd duplicate an interrupt request 20.Sh SYNOPSIS 21.In sys/usb/usba/hcdi.h 22.Ft usb_intr_req_t * 23.Fo usba_hcdi_dup_intr_req 24.Fa "dev_info_t *dip" 25.Fa "usb_intr_req_t *irqp" 26.Fa "size_t size" 27.Fa "usb_flags_t flags" 28.Fc 29.Sh INTERFACE LEVEL 30.Sy Volatile - 31illumos USB HCD private function 32.Pp 33This is a private function that is not part of the stable DDI. 34It may be removed or changed at any time. 35.Sh PARAMETERS 36.Bl -tag -width Fa 37.It Fa dip 38A pointer to the HCD driver's 39.Sy dev_info 40structure. 41.It Fa irqp 42A pointer to the USB interrupt request which will be duplicated. 43.It Fa size 44The number of bytes in the allocated data block 45.Sy mblk_t . 46.It Fa flags 47Flags which describe how allocations should be performed. 48Valid flags are: 49.Bl -tag -width Sy 50.It Sy USB_FLAGS_NOSLEEP 51Do not block waiting for memory. 52If memory is not available the allocation will fail. 53.It Sy USB_FLAGS_SLEEP 54Perform a blocking allocation. 55If memory is not available, the function will wait until memory is made 56available. 57.Pp 58Note, the request may still fail even if 59.Sy USB_FLAGS_SLEEP 60is specified. 61.El 62.El 63.Sh DESCRIPTION 64The 65.Fn usba_hcdi_dup_intr_req 66function is used to duplicate an existing interrupt request, 67.Fa irqp . 68.Pp 69The USBA framework initiates interrupt operations through the 70.Xr usba_hcdi_pipe_intr_xfer 9E 71entry point. 72It provides an initial USB interrupt request as an argument. 73When the HCD driver has interrupt data to return, it needs to duplicate 74that initial interrupt request each time that it submits data through 75the 76.Xr usba_hcdi_cb 9F 77function. 78In addition to duplicating the request, callers may also need to increase the 79pipe handle's request count. 80For more information, see 81.Xr usba_hcdi_pipe_intr_xfer 9E . 82.Pp 83The 84.Fa dip 85argument should correspond to the HCD driver's 86.Sy dev_info_t 87structure. 88The 89.Fa irqp 90pointer should correspond to the initial interrupt request. 91The 92.Fa size 93argument should describe the maximum amount of data needed for this request. 94The amount of data will be dependent on the endpoint and device. 95The value of 96.Fa flags 97should depend on the caller's context. 98If 99.Dv USB_FLAGS_SLEEP 100is passed while in interrupt context, then this function will fail. 101.Sh CONTEXT 102The 103.Fn usba_hcdi_dup_intr_req 104function may be called from 105.Sy user , 106.Sy kernel , 107or 108.Sy interrupt 109context; however, when in interrupt context, the value of 110.Fa flags 111must be 112.Sy USB_FLAGS_NOSLEEP . 113.Sh RETURN VALUES 114Upon successful completion, the 115.Fn usba_hcdi_dup_intr_req 116function returns a pointer to a duplicated interrupt request. 117Otherwise, 118.Sy NULL 119is returned to indicate that the request could not be duplicated. 120.Sh SEE ALSO 121.Xr usba_hcdi 9E , 122.Xr usba_hcdi_pipe_intr_xfer 9E , 123.Xr usba_hcdi_cb 9F 124