usr/src/man/man9f/usba_hcdi_dup_isoc_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 Sep 16, 2016
  15 .Dt USBA_HCDI_DUP_ISOC_REQ 9F
  16 .Os
  17 .Sh NAME
  18 .Nm usba_hcdi_dup_isoc_req
  19 .Nd duplicate an isochronous request
  20 .Sh SYNOPSIS
  21 .In sys/usb/usba/hcdi.h
  22 .Ft "usb_isoc_req_t *"
  23 .Fo usba_hcdi_dup_isoc_req
  24 .Fa "dev_info_t *dip"
  25 .Fa "usb_isoc_req_t *usrp"
  26 .Fa "usb_flags_t flags"
  27 .Fc
  28 .Sh INTERFACE LEVEL
  29 .Sy Volatile -
  30 illumos USB HCD private function
  31 .Pp
  32 This is a private function that is not part of the stable DDI.
  33 It may be removed or changed at any time.
  34 .Sh PARAMETERS
  35 .Bl -tag -width Fa
  36 .It Fa dip
  37 A pointer to the HCD driver's
  38 .Sy dev_info
  39 structure.
  40 .It Fa usrp
  41 A pointer to the USB isochronous request which will be duplicated.
  42 .It Fa flags
  43 .Bl -tag -width Sy
  44 .It Sy USB_FLAGS_NOSLEEP
  45 Do not block waiting for memory.
  46 If memory is not available the allocation will fail.
  47 .It Sy USB_FLAGS_SLEEP
  48 Perform a blocking allocation.
  49 If memory is not available, the function will wait until memory is made
  50 available.
  51 .Pp
  52 Note, the request may still fail even if
  53 .Sy USB_FLAGS_SLEEP
  54 is specified.
  55 .El
  56 .El
  57 .Sh DESCRIPTION
  58 The
  59 .Fn usba_hcdi_dup_isoc_req
  60 function is used to duplicate an existing isochronous request,
  61 .Fa usrp .
  62 .Pp
  63 When the USBA framework initiates an isochronous in transfer with the
  64 .Xr usba_hcdi_pipe_isoc_xfer 9E
  65 entry point, it is the HCD driver's responsibility to receive the
  66 periodic data from the pipe.
  67 When there is data available, the HCD must duplicate the original isochronous
  68 request and copy the available data into the request structure's
  69 .Fa isoc_data
  70 member, before handing over the request structure to the USBA framework
  71 by calling the
  72 .Xr usba_hcdi_cb 9F
  73 function.
  74 .Pp
  75 In addition to duplicating the request, it is the callers responsibility
  76 to increase the pipe handle's request count.
  77 For more information, see
  78 .Xr usba_hcdi_pipe_isoc_xfer 9E .
  79 .Pp
  80 The
  81 .Fa dip
  82 argument should correspond to the HCD driver's
  83 .Sy dev_info_t
  84 structure.
  85 The
  86 .Fa usrp
  87 pointer should correspond to the initial isochronous request.
  88 The
  89 .Fa flags
  90 member must be appropriate for the context.
  91 If
  92 .Dv USB_FLAGS_SLEEP
  93 is passed while in interrupt context, then this function may fail.
  94 .Sh CONTEXT
  95 The
  96 .Fn usba_hcdi_dup_isoc_req
  97 function may be called from
  98 .Sy user ,
  99 .Sy kernel ,
 100 or
 101 .Sy interrupt
 102 context; however, when in interrupt context, the value of
 103 .Fa flags
 104 must be
 105 .Sy USB_FLAGS_NOSLEEP .
 106 .Sh RETURN VALUES
 107 Upon successful completion, the
 108 .Fn usba_hcdi_dup_isoc_req
 109 function returns a pointer to a duplicate isochronous request.
 110 Otherwise,
 111 .Sy NULL
 112 is returned to indicate that the request could not be duplicated.
 113 .Sh SEE ALSO
 114 .Xr usba_hcdi 9E ,
 115 .Xr usba_hcdi_pipe_isoc_xfer 9E ,
 116 .Xr usba_hcdi_cb 9F