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