'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH USBMS 7M "Dec 1, 2005"
.SH NAME
usbms \- USB mouse STREAMS module
.SH SYNOPSIS
.LP
.nf
#include <sys/vuid_event.h>
.fi

.LP
.nf
#include <sys/vuid_wheel.h>
.fi

.LP
.nf
#include <sys/msio.h>
.fi

.LP
.nf
#include <sys/msreg.h>
.fi

.SH DESCRIPTION
.sp
.LP
The  \fBusbms\fR \fBSTREAMS\fR module processes byte streams generated by a
\fBUSB\fR mouse.  A  \fBUSB\fR mouse is a member of the Human Interface Device
(HID) class and the  \fBusbms\fR module supports only the mouse boot protocol
defined in the \fBHID\fR specification.
.sp
.LP
The \fBusbms\fR module must be pushed on top of the \fBHID\fR class driver (see
\fBhid\fR(7D)). In the  \fBVUID_FIRM_EVENT\fR mode, the \fBusbms\fR module
translates packets from the \fBUSB\fR mouse into Firm events. The Firm event
structure is defined in \fB<sys/vuid_event.h>\fR\&. The  \fBSTREAMS\fR module
state is initially set to raw or \fBVUID_NATIVE\fR mode which performs no
message processing. See the  \fIHID 1.0\fR specification for the raw format of
the mouse packets. To initiate mouse protocol conversion to Firm events, change
the state to \fBVUID_FIRM_EVENT\fR.
.sp
.LP
When the usb mouse is opened or hot plugged in, the MOUSE_TYPE_ABSOLUTE  event
(Firm event) is sent to the upper level to notify the VUID application that it
is the absolute mouse.
.SH IOCTLS
.sp
.ne 2
.na
\fB\fBVUIDGFORMAT\fR \fR
.ad
.RS 16n
This option returns the current state of the  \fBSTREAMS\fR module. The state
of the \fBusbms\fR \fBSTREAMS\fR module may be either \fBVUID_NATIVE\fR (no
message processing) or \fBVUID_FIRM_EVENT\fR (convert to Firm events).
.RE

.sp
.ne 2
.na
\fB\fBVUIDSFORMAT\fR \fR
.ad
.RS 16n
The argument is a pointer to an \fBint\fR. Set the state of the  \fBSTREAMS\fR
module to the \fBint\fR pointed to by the argument.
.RE

.sp
.in +2
.nf
typedef struct  vuid_addr_probe {
     short base; /* default vuid device addr directed too */
     union {
            short next;   /* next addr for default when VUIDSADDR */
            short current; /* current addr of default when VUIDGADDR */
     } data;
} Vuid_addr_probe;
.fi
.in -2

.sp
.ne 2
.na
\fB\fBVUIDSADDR\fR \fR
.ad
.RS 14n
The argument is a pointer to a \fBVuid_addr_probe\fR structure.
\fBVUIDSADDR\fR sets the virtual input device segment address indicated by base
to next.
.RE

.sp
.LP
If base does not equal \fBVKEY_FIRST\fR,  \fBENODEV\fR is returned.
.sp
.ne 2
.na
\fB\fBVUIDGADDR\fR \fR
.ad
.RS 14n
The argument is a pointer to a \fBVuid_addr_probe\fR structure. Return the
address of the virtual input device segment indicated by base to current.
.RE

.sp
.LP
If base does not equal \fBVKEY_FIRST\fR, \fBENODEV\fR is returned.
.sp
.ne 2
.na
\fBVUIDGWHEELCOUNT\fR
.ad
.sp .6
.RS 4n
This ioctl takes a pointer to an integer as argument and sets the value of the
integer to the number of wheels available on this device. This ioctl returns 1
if wheel(s) are present and zero if no wheels are present.
.RE

.sp
.ne 2
.na
\fBVUIDGWHEELINFO\fR
.ad
.sp .6
.RS 4n
This command returns static information about the wheel that does not  change
while a device is in use. Currently the only information  defined  is  the
wheel orientation which is either VUID_WHEEL_FORMAT_VERTICAL or
VUID_WHEEL_FORMAT_HORIZONTAL. If the module cannot distinguish the orientation
of the wheel or the wheel is of some other format, the format is set to
VUID_WHEEL_FORMAT_UNKNOWN.
.sp
.in +2
.nf
   typedef struct {
           int     vers;
           int     id;
           int     format;
   } wheel_info;
.fi
.in -2

The  ioctl  takes a pointer to "wheel_info" structure with the "vers" set to
the current version of the "wheel_info" structure and "id" set to the id of the
wheel for which the information is desired.
.RE

.sp
.ne 2
.na
\fBVUIDSWHEELSTATE/VUIDGWHEELSTATE\fR
.ad
.sp .6
.RS 4n
VUIDSWHEELSTATE sets the state of the wheel to that specified in the
stateflags. VUIDGWHEELSTATE returns the current state settings in the
stateflags field.
.sp
stateflags is an  OR'ed  set of  flag  bits. The only flag currently defined is
VUID_WHEEL_STATE_ENABLED.
.sp
When stateflags is set to VUID_WHEEL_STATE_ENABLED the module converts motion
of the specified wheel into VUID events and sends those up stream.
.sp
Wheel events are enabled by default.
.sp
Applications that want to change the stateflags should first get the current
stateflags and then change only the bit they want.
.sp
.in +2
.nf
   typedef struct {
           int            vers;
           int            id;
           uint32_t       stateflags;
   } wheel_state;
.fi
.in -2

These ioctls take a pointer to "wheel_state" as an argument with  the "vers"
and "id" members filled in. These members have the same meaning as that
for 'VUIDGWHEEL INFO' ioctl.
.RE

.sp
.LP
\fBioctl()\fR requests for changing and retrieving mouse parameters use the
\fBMs_parms\fR structure:
.sp
.in +2
.nf
   typedef struct {
        int     jitter_thresh;
        int     speed_law;
        int     speed_limit;
   } Ms_parms;
.fi
.in -2

.sp
.LP
\fBjitter_thresh\fR is the "jitter threshold" of the mouse.  Motions fewer than
\fBjitter_thresh\fR units along both axes are accumulated and then sent up the
stream after 1/12 second.
.sp
.LP
\fBspeed_law\fR indicates whether extremely large motions are to be ignored. If
it is \fB1,\fR a "speed limit" is applied to mouse motions.  Motions along
either axis of more than \fBspeed_limit\fR units are discarded.
.sp
.ne 2
.na
\fB\fBMSIOGETPARMS\fR \fR
.ad
.RS 19n
The argument is a pointer to a \fBMs_params\fR structure. The \fBusbms\fR
module parameters are returned in the structure.
.RE

.sp
.ne 2
.na
\fB\fBMSIOSETPARMS\fR\fR
.ad
.RS 19n
The argument is a pointer to a \fBMs_params\fR structure. The \fBusbms\fR
module parameters are set according to the values in the structure.
.RE

.sp
.ne 2
.na
\fB\fBMSIOSRESOLUTION\fR\fR
.ad
.RS 19n
Used by the absolute mouse to get the  current screen resolution. The parameter
is a pointer to the \fBMs_screen_resolution\fR structure:
.sp
.in +2
.nf
int    height;         /* height of the screen */
int    width;         /* width of the screen */
}Ms_screen_resolution;
.fi
.in -2

The \fBusbms\fR module parameters are set according to the values in the
structure and used to calculate the correct coordinates.
.RE

.SH FILES
.sp
.ne 2
.na
\fB/kernel/strmod/usbms\fR
.ad
.sp .6
.RS 4n
32-bit ELF kernel STREAMS module (x86 platform only.)
.RE

.sp
.ne 2
.na
\fB/kernel/strmod/sparcv9/usbms\fR
.ad
.sp .6
.RS 4n
SPARC 64-bit ELF kernel STREAMS module
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for a description of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Architecture	PCI-based  systems
.TE

.SH SEE ALSO
.sp
.LP
\fBioctl\fR(2), \fBattributes\fR(5), \fBhid\fR(7D), \fBvirtualkm\fR(7D),
\fBusba\fR(7D)
.sp
.LP
\fISystem Administration Guide: Basic Administration\fR
.sp
.LP
http://\fIwww/sun.com/io\fR
.SH DIAGNOSTICS
.sp
.LP
The following messages may be logged into the system log. They are formatted in
the following manner:
.sp
.in +2
.nf
<device path><usbms<instance number>): message...
.fi
.in -2
.sp

.sp
.ne 2
.na
\fBInvalid Hid descriptor tree. Set to default value (3 buttons).\fR
.ad
.sp .6
.RS 4n
The mouse supplied incorrect information in its HID report.
.RE

.sp
.ne 2
.na
\fBMouse buffer flushed when overrun.\fR
.ad
.sp .6
.RS 4n
Mouse data was lost.
.RE