usr/src/man/man7m/usbms.7m

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH USBMS 7M "May 13, 2017"
   7 .SH NAME
   8 usbms \- USB mouse STREAMS module
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <sys/vuid_event.h>
  13 .fi
  14
  15 .LP
  16 .nf
  17 #include <sys/vuid_wheel.h>
  18 .fi
  19
  20 .LP
  21 .nf
  22 #include <sys/msio.h>
  23 .fi
  24
  25 .LP
  26 .nf
  27 #include <sys/msreg.h>
  28 .fi
  29
  30 .SH DESCRIPTION
  31 .LP
  32 The \fBusbms\fR \fBSTREAMS\fR module processes byte streams generated by a
  33 \fBUSB\fR mouse.  A \fBUSB\fR mouse is a member of the Human Interface Device
  34 (HID) class and the \fBusbms\fR module supports only the mouse boot protocol
  35 defined in the \fBHID\fR specification.
  36 .sp
  37 .LP
  38 The \fBusbms\fR module must be pushed on top of the \fBHID\fR class driver (see
  39 \fBhid\fR(7D)). In the \fBVUID_FIRM_EVENT\fR mode, the \fBusbms\fR module
  40 translates packets from the \fBUSB\fR mouse into Firm events. The Firm event
  41 structure is defined in \fB<sys/vuid_event.h>\fR\&. The \fBSTREAMS\fR module
  42 state is initially set to raw or \fBVUID_NATIVE\fR mode which performs no
  43 message processing. See the \fIHID 1.0\fR specification for the raw format of
  44 the mouse packets. To initiate mouse protocol conversion to Firm events, change
  45 the state to \fBVUID_FIRM_EVENT\fR.
  46 .sp
  47 .LP
  48 When the usb mouse is opened or hot plugged in, the MOUSE_TYPE_ABSOLUTE event
  49 (Firm event) is sent to the upper level to notify the VUID application that it
  50 is the absolute mouse.
  51 .SH IOCTLS
  52 .ne 2
  53 .na
  54 \fB\fBVUIDGFORMAT\fR \fR
  55 .ad
  56 .RS 16n
  57 This option returns the current state of the \fBSTREAMS\fR module. The state
  58 of the \fBusbms\fR \fBSTREAMS\fR module may be either \fBVUID_NATIVE\fR (no
  59 message processing) or \fBVUID_FIRM_EVENT\fR (convert to Firm events).
  60 .RE
  61
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fBVUIDSFORMAT\fR \fR
  66 .ad
  67 .RS 16n
  68 The argument is a pointer to an \fBint\fR. Set the state of the \fBSTREAMS\fR
  69 module to the \fBint\fR pointed to by the argument.
  70 .RE
  71
  72 .sp
  73 .in +2
  74 .nf
  75 typedef struct  vuid_addr_probe {
  76      short base; /* default vuid device addr directed too */
  77      union {
  78             short next;   /* next addr for default when VUIDSADDR */
  79             short current; /* current addr of default when VUIDGADDR */
  80      } data;
  81 } Vuid_addr_probe;
  82 .fi
  83 .in -2
  84
  85 .sp
  86 .ne 2
  87 .na
  88 \fB\fBVUIDSADDR\fR \fR
  89 .ad
  90 .RS 14n
  91 The argument is a pointer to a \fBVuid_addr_probe\fR structure.
  92 \fBVUIDSADDR\fR sets the virtual input device segment address indicated by base
  93 to next.
  94 .RE
  95
  96 .sp
  97 .LP
  98 If base does not equal \fBVKEY_FIRST\fR, \fBENODEV\fR is returned.
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBVUIDGADDR\fR \fR
 103 .ad
 104 .RS 14n
 105 The argument is a pointer to a \fBVuid_addr_probe\fR structure. Return the
 106 address of the virtual input device segment indicated by base to current.
 107 .RE
 108
 109 .sp
 110 .LP
 111 If base does not equal \fBVKEY_FIRST\fR, \fBENODEV\fR is returned.
 112 .sp
 113 .ne 2
 114 .na
 115 \fBVUIDGWHEELCOUNT\fR
 116 .ad
 117 .sp .6
 118 .RS 4n
 119 This ioctl takes a pointer to an integer as argument and sets the value of the
 120 integer to the number of wheels available on this device. This ioctl returns 1
 121 if wheel(s) are present and zero if no wheels are present.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fBVUIDGWHEELINFO\fR
 128 .ad
 129 .sp .6
 130 .RS 4n
 131 This command returns static information about the wheel that does not change
 132 while a device is in use. Currently the only information defined is the
 133 wheel orientation which is either VUID_WHEEL_FORMAT_VERTICAL or
 134 VUID_WHEEL_FORMAT_HORIZONTAL. If the module cannot distinguish the orientation
 135 of the wheel or the wheel is of some other format, the format is set to
 136 VUID_WHEEL_FORMAT_UNKNOWN.
 137 .sp
 138 .in +2
 139 .nf
 140    typedef struct {
 141            int     vers;
 142            int     id;
 143            int     format;
 144    } wheel_info;
 145 .fi
 146 .in -2
 147
 148 The ioctl takes a pointer to "wheel_info" structure with the "vers" set to
 149 the current version of the "wheel_info" structure and "id" set to the id of the
 150 wheel for which the information is desired.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fBVUIDSWHEELSTATE/VUIDGWHEELSTATE\fR
 157 .ad
 158 .sp .6
 159 .RS 4n
 160 VUIDSWHEELSTATE sets the state of the wheel to that specified in the
 161 stateflags. VUIDGWHEELSTATE returns the current state settings in the
 162 stateflags field.
 163 .sp
 164 stateflags is an OR'ed set of flag bits. The only flag currently defined is
 165 VUID_WHEEL_STATE_ENABLED.
 166 .sp
 167 When stateflags is set to VUID_WHEEL_STATE_ENABLED the module converts motion
 168 of the specified wheel into VUID events and sends those up stream.
 169 .sp
 170 Wheel events are enabled by default.
 171 .sp
 172 Applications that want to change the stateflags should first get the current
 173 stateflags and then change only the bit they want.
 174 .sp
 175 .in +2
 176 .nf
 177    typedef struct {
 178            int            vers;
 179            int            id;
 180            uint32_t       stateflags;
 181    } wheel_state;
 182 .fi
 183 .in -2
 184
 185 These ioctls take a pointer to "wheel_state" as an argument with the "vers"
 186 and "id" members filled in. These members have the same meaning as that
 187 for 'VUIDGWHEEL INFO' ioctl.
 188 .RE
 189
 190 .sp
 191 .LP
 192 \fBioctl()\fR requests for changing and retrieving mouse parameters use the
 193 \fBMs_parms\fR structure:
 194 .sp
 195 .in +2
 196 .nf
 197    typedef struct {
 198         int     jitter_thresh;
 199         int     speed_law;
 200         int     speed_limit;
 201    } Ms_parms;
 202 .fi
 203 .in -2
 204
 205 .sp
 206 .LP
 207 \fBjitter_thresh\fR is the "jitter threshold" of the mouse.  Motions fewer than
 208 \fBjitter_thresh\fR units along both axes are accumulated and then sent up the
 209 stream after 1/12 second.
 210 .sp
 211 .LP
 212 \fBspeed_law\fR indicates whether extremely large motions are to be ignored. If
 213 it is \fB1,\fR a "speed limit" is applied to mouse motions.  Motions along
 214 either axis of more than \fBspeed_limit\fR units are discarded.
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBMSIOGETPARMS\fR \fR
 219 .ad
 220 .RS 19n
 221 The argument is a pointer to a \fBMs_params\fR structure. The \fBusbms\fR
 222 module parameters are returned in the structure.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fBMSIOSETPARMS\fR\fR
 229 .ad
 230 .RS 19n
 231 The argument is a pointer to a \fBMs_params\fR structure. The \fBusbms\fR
 232 module parameters are set according to the values in the structure.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBMSIOSRESOLUTION\fR\fR
 239 .ad
 240 .RS 19n
 241 Used by the absolute mouse to get the current screen resolution. The parameter
 242 is a pointer to the \fBMs_screen_resolution\fR structure:
 243 .sp
 244 .in +2
 245 .nf
 246 int    height;         /* height of the screen */
 247 int    width;         /* width of the screen */
 248 }Ms_screen_resolution;
 249 .fi
 250 .in -2
 251
 252 The \fBusbms\fR module parameters are set according to the values in the
 253 structure and used to calculate the correct coordinates.
 254 .RE
 255
 256 .SH FILES
 257 .ne 2
 258 .na
 259 \fB/kernel/strmod/usbms\fR
 260 .ad
 261 .sp .6
 262 .RS 4n
 263 32-bit ELF kernel STREAMS module (x86 platform only.)
 264 .RE
 265
 266 .sp
 267 .ne 2
 268 .na
 269 \fB/kernel/strmod/sparcv9/usbms\fR
 270 .ad
 271 .sp .6
 272 .RS 4n
 273 SPARC 64-bit ELF kernel STREAMS module
 274 .RE
 275
 276 .SH ATTRIBUTES
 277 .LP
 278 See \fBattributes\fR(5) for a description of the following attributes:
 279 .sp
 280
 281 .sp
 282 .TS
 283 box;
 284 c | c
 285 l | l .
 286 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 287 _
 288 Architecture    PCI-based  systems
 289 .TE
 290
 291 .SH SEE ALSO
 292 .LP
 293 \fBioctl\fR(2), \fBattributes\fR(5), \fBhid\fR(7D), \fBvirtualkm\fR(7D),
 294 \fBusba\fR(7D)
 295 .sp
 296 .LP
 297 \fISystem Administration Guide: Basic Administration\fR
 298 .SH DIAGNOSTICS
 299 .LP
 300 The following messages may be logged into the system log. They are formatted in
 301 the following manner:
 302 .sp
 303 .in +2
 304 .nf
 305 <device path><usbms<instance number>): message...
 306 .fi
 307 .in -2
 308 .sp
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fBInvalid Hid descriptor tree. Set to default value (3 buttons).\fR
 314 .ad
 315 .sp .6
 316 .RS 4n
 317 The mouse supplied incorrect information in its HID report.
 318 .RE
 319
 320 .sp
 321 .ne 2
 322 .na
 323 \fBMouse buffer flushed when overrun.\fR
 324 .ad
 325 .sp .6
 326 .RS 4n
 327 Mouse data was lost.
 328 .RE
 329