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. It may be 34removed 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. Valid flags 48are: 49.Bl -tag -width Sy 50.It Sy USB_FLAGS_NOSLEEP 51Do not block waiting for memory. If memory is not available the allocation 52will fail. 53.It Sy USB_FLAGS_SLEEP 54Perform a blocking allocation. If memory is not available, the function 55will wait until memory is made available. 56.Pp 57Note, the request may still fail even if 58.Sy USB_FLAGS_SLEEP 59is specified. 60.El 61.El 62.Sh DESCRIPTION 63The 64.Fn usba_hcdi_dup_intr_req 65function is used to duplicate an existing interrupt request, 66.Fa irqp . 67.Pp 68The USBA framework initiates interrupt operations through the 69.Xr usba_hcdi_pipe_intr_xfer 9E 70entry point. It provides an initial USB interrupt request as an argument. 71When the HCD driver has interrupt data to return, it needs to duplicate 72that initial interrupt request each time that it submits data through 73the 74.Xr usba_hcdi_cb 9F 75function. In addition to duplicating the request, callers may also need 76to increase the pipe handle's request count. For more information, see 77.Xr usba_hcdi_pipe_intr_xfer 9E . 78.Pp 79The 80.Fa dip 81argument should correspond to the HCD driver's 82.Sy dev_info_t 83structure. The 84.Fa irqp 85pointer should correspond to the initial interrupt request. The 86.Fa size 87argument should describe the maximum amount of data needed for this 88request. The amount of data will be dependent on the endpoint and 89device. The value of 90.Fa flags 91should depend on the caller's context. If 92.Dv USB_FLAGS_SLEEP 93is passed while in interrupt context, then this function will fail. 94.Sh CONTEXT 95The 96.Fn usba_hcdi_dup_intr_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_intr_req 109function returns a pointer to a duplicated interrupt request. Otherwise, 110.Sy NULL 111is returned to indicate that the request could not be duplicated. 112.Sh SEE ALSO 113.Xr usba_hcdi 9E , 114.Xr usba_hcdi_pipe_intr_xfer 9E , 115.Xr usba_hcdi_cb 9F 116