usr/src/man/man9f/usba_hcdi_dup_intr_req.9f

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