usr/src/man/man9s/usba_pipe_handle_data.9s

   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 Dec 20, 2016
  15 .Dt USBA_PIPE_HANDLE_DATA 9S
  16 .Os
  17 .Sh NAME
  18 .Nm usba_pipe_handle_data ,
  19 .Nm usba_pipe_handle_data_t
  20 .Nd USBA Pipe Handle Data Structure
  21 .Sh SYNOPSIS
  22 .In sys/usb/usba/hcdi.h
  23 .Sh INTERFACE LEVEL
  24 .Sy Volatile -
  25 illumos USB HCD private
  26 .Pp
  27 This is a private data structure that is not part of the stable DDI.
  28 It may be removed or changed at any time.
  29 .Sh DESCRIPTION
  30 The
  31 .Sy usba_pipe_handle_data
  32 structure is the USB architecture's (USBA) way of representing a pipe.
  33 Every pipe is a part of a USB device.
  34 Pipe's may be shared between client drivers or be exclusive to one.
  35 For more background on pipe's see the
  36 .Sy USB Endpoint Background
  37 section of
  38 .Xr usba_hcdi 9E .
  39 .Pp
  40 This structure is provided to HCD driver's when performing requests of
  41 various kinds.
  42 The majority of the structures listed here are
  43 .Em read-only ;
  44 however, HCD drivers are allowed to update a single member, listed
  45 below.
  46 All of the writable members are protected by a lock, the member
  47 .Sy p_mutex .
  48 See the
  49 .Sy Locking
  50 section in
  51 .Xr usba_hcdi 9E
  52 for more information on lock ordering and when HCD drivers should enter
  53 this lock.
  54 .Pp
  55 A pipe handle has an explicit life cycle wih a device driver.
  56 The driver first sees the pipe handle when its
  57 .Xr usba_hcdi_pipe_open 9E
  58 entry point is called.
  59 At that time, the HCD driver has the change to store private data on the handle.
  60 This pipe handle will be used in subsequent requests until the handle is closed,
  61 through a call to the HCD driver's
  62 .Xr usba_hcdi_pipe_close 9E
  63 entry point.
  64 .Sh STRUCTURE MEMBERS
  65 The
  66 .Sy usba_pipe_handle_data_t
  67 structure includes the following members:
  68 .Bd -literal -offset -indent
  69 usba_device_t           *p_usba_device;
  70 usb_ep_descr_t          p_ep;
  71 usb_ep_xdescr_t         p_xep;
  72 dev_info_t              p_dip;
  73 usb_opaque_t            p_hcd_private;
  74 kmutex_t                p_mutex;
  75 int                     p_req_count;
  76 .Ed
  77 .Pp
  78 The
  79 .Sy p_usba_device
  80 member points to the
  81 .Xr usba_device 9S
  82 structure that this pipe belongs to.
  83 This member should always be set for an endpoint handed to an HCD driver.
  84 .Pp
  85 The
  86 .Sy p_ep
  87 member is filled in with the endpoint descriptor that represents this
  88 device.
  89 The endpoint structure is documented in
  90 .Xr usb_ep_descr 9S .
  91 .Pp
  92 The
  93 .Sy p_xep
  94 member is filled in with the endpoint descriptor and any additional
  95 endpoint descriptors that may exist.
  96 The structure is documented in
  97 .Xr usb_ep_xdescr 9S .
  98 The endpoint descriptor is the same in both
  99 .Sy p_ep
 100 and
 101 .Sy p_xep .
 102 .Pp
 103 The
 104 .Sy p_hcd_private
 105 member is reserved for use with HCD drivers.
 106 An HCD driver may set this member during
 107 .Xr usba_hcdi_pipe_open 9E .
 108 If set, it can reference this member throughout the life time of the
 109 pipe.
 110 The driver should ensure to clean it up when its
 111 .Xr usba_hcdi_pipe_close 9E
 112 entry point is called.
 113 .Pp
 114 The
 115 .Sy p_mutex
 116 member protects the member
 117 .Sy p_req_count .
 118 The mutex should be entered whenever the value is being manipulated.
 119 .Pp
 120 The
 121 .Sy p_req_count
 122 member indicates the number of outstanding requests on the pipe.
 123 When performing
 124 .Em periodic
 125 interrupt or isochronous transfers, it is the responsibility of the HCD
 126 driver to increment the value of
 127 .Sy p_req_count
 128 if it duplicates a request with either
 129 .Xr usba_hcdi_dup_intr_req 9F
 130 or
 131 .Xr usba_hcdi_dup_isoc_req 9F .
 132 .Pp
 133 Similarly, if the device driver for some reasons removes a request it
 134 duplicated without submitting it to the USBA, it should decrement the
 135 member.
 136 .Pp
 137 The HCD driver should take special care to ensure that the value of
 138 .Sy p_req_count
 139 is always greater than one.
 140 There should always be an outstanding request that an HCD driver has for the
 141 pipe, especially if it is a periodic endpoint.
 142 It should only manipulate this member while it owns
 143 .Sy p_mutex .
 144 .Sh SEE ALSO
 145 .Xr usba_hcdi_pipe_close 9E ,
 146 .Xr usba_hcdi_pipe_open 9E ,
 147 .Xr usba_hcdi_dup_intr_req 9F ,
 148 .Xr usba_hcdi_dup_isoc_req 9F ,
 149 .Xr usb_ep_descr 9S ,
 150 .Xr usb_ep_xdescr 9S ,
 151 .Xr usba_device 9S