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