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