.\"
.\" This file and its contents are supplied under the terms of the
.\" Common Development and Distribution License ("CDDL"), version 1.0.
.\" You may only use this file in accordance with the terms of version
.\" 1.0 of the CDDL.
.\"
.\" A full copy of the text of the CDDL should have accompanied this
.\" source.  A copy of the CDDL is also available via the Internet at
.\" http://www.illumos.org/license/CDDL.
.\"
.\"
.\" Copyright 2016 Joyent, Inc.
.\"
.Dd May 10, 2016
.Dt USBA_HCDI_DUP_INTER_REQ 9F
.Os
.Sh NAME
.Nm usba_hcdi_dup_intr_req
.Nd duplicate an interrupt request
.Sh SYNOPSIS
.In sys/usb/usba/hcdi.h
.Ft usb_intr_req_t *
.Fo usba_hcdi_dup_intr_req
.Fa "dev_info_t *dip"
.Fa "usb_intr_req_t *irqp"
.Fa "size_t size"
.Fa "usb_flags_t flags"
.Fc
.Sh INTERFACE LEVEL
.Sy Volatile -
illumos USB HCD private function
.Pp
This is a private function that is not part of the stable DDI.
It may be removed or changed at any time.
.Sh PARAMETERS
.Bl -tag -width Fa
.It Fa dip
A pointer to the HCD driver's
.Sy dev_info
structure.
.It Fa irqp
A pointer to the USB interrupt request which will be duplicated.
.It Fa size
The number of bytes in the allocated data block
.Sy mblk_t .
.It Fa flags
Flags which describe how allocations should be performed.
Valid flags are:
.Bl -tag -width Sy
.It Sy USB_FLAGS_NOSLEEP
Do not block waiting for memory.
If memory is not available the allocation will fail.
.It Sy USB_FLAGS_SLEEP
Perform a blocking allocation.
If memory is not available, the function will wait until memory is made
available.
.Pp
Note, the request may still fail even if
.Sy USB_FLAGS_SLEEP
is specified.
.El
.El
.Sh DESCRIPTION
The
.Fn usba_hcdi_dup_intr_req
function is used to duplicate an existing interrupt request,
.Fa irqp .
.Pp
The USBA framework initiates interrupt operations through the
.Xr usba_hcdi_pipe_intr_xfer 9E
entry point.
It provides an initial USB interrupt request as an argument.
When the HCD driver has interrupt data to return, it needs to duplicate
that initial interrupt request each time that it submits data through
the
.Xr usba_hcdi_cb 9F
function.
In addition to duplicating the request, callers may also need to increase the
pipe handle's request count.
For more information, see
.Xr usba_hcdi_pipe_intr_xfer 9E .
.Pp
The
.Fa dip
argument should correspond to the HCD driver's
.Sy dev_info_t
structure.
The
.Fa irqp
pointer should correspond to the initial interrupt request.
The
.Fa size
argument should describe the maximum amount of data needed for this request.
The amount of data will be dependent on the endpoint and device.
The value of
.Fa flags
should depend on the caller's context.
If
.Dv USB_FLAGS_SLEEP
is passed while in interrupt context, then this function will fail.
.Sh CONTEXT
The
.Fn usba_hcdi_dup_intr_req
function may be called from
.Sy user ,
.Sy kernel ,
or
.Sy interrupt
context; however, when in interrupt context, the value of
.Fa flags
must be
.Sy USB_FLAGS_NOSLEEP .
.Sh RETURN VALUES
Upon successful completion, the
.Fn usba_hcdi_dup_intr_req
function returns a pointer to a duplicated interrupt request.
Otherwise,
.Sy NULL
is returned to indicate that the request could not be duplicated.
.Sh SEE ALSO
.Xr usba_hcdi 9E ,
.Xr usba_hcdi_pipe_intr_xfer 9E ,
.Xr usba_hcdi_cb 9F