3 .\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer as
11 .\" the first lines of this file unmodified.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
17 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
20 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
34 .Nd mouse and pointing device drivers
43 provide user programs with movement and button state information of the mouse.
44 Currently there are specific device drivers for bus, InPort, PS/2, and USB mice.
45 The serial mouse is not directly supported by a dedicated driver, but
46 it is accessible via the serial device driver or via
51 The user program simply opens a mouse device with a
54 mouse data from the device via
56 Movement and button states are usually encoded in fixed-length data packets.
57 Some mouse devices may send data in variable length of packets.
58 Actual protocol (data format) used by each driver differs widely.
60 The mouse drivers may have ``non-blocking'' attribute which will make
61 the driver return immediately if mouse data is not available.
63 Mouse device drivers often offer several levels of operation.
64 The current operation level can be examined and changed via
67 The level zero is the lowest level at which the driver offers the basic
68 service to user programs.
69 Most drivers provide horizontal and vertical movement of the mouse
70 and state of up to three buttons at this level.
71 At the level one, if supported by the driver, mouse data is encoded
72 in the standard format
73 .Dv MOUSE_PROTO_SYSMOUSE
76 .Bl -tag -width Byte_1 -compact
78 .Bl -tag -width bit_7 -compact
84 Left button status; cleared if pressed, otherwise set.
86 Middle button status; cleared if pressed, otherwise set.
88 if the device does not have the middle button.
90 Right button status; cleared if pressed, otherwise set.
93 The first half of horizontal movement count in two's complement;
96 The first half of vertical movement count in two's complement;
99 The second half of the horizontal movement count in two's complement;
101 To obtain the full horizontal movement count, add
104 The second half of the vertical movement count in two's complement;
106 To obtain the full vertical movement count, add
109 The bit 7 is always zero.
110 The lower 7 bits encode the first half of
111 Z axis movement count in two's complement; -64 through 63.
113 The bit 7 is always zero.
114 The lower 7 bits encode the second half of
115 the Z axis movement count in two's complement; -64 through 63.
116 To obtain the full Z axis movement count, add the byte 6 and 7.
118 The bit 7 is always zero.
119 The bits 0 through 6 reflect the state
120 of the buttons 4 through 10.
121 If a button is pressed, the corresponding bit is cleared.
126 The first 5 bytes of this format is compatible with the MouseSystems
128 The additional 3 bytes have their MSBs always set to zero.
129 Thus, if the user program can interpret the MouseSystems data format and
130 tries to find the first byte of the format by detecting the bit pattern
132 it will discard the additional bytes, thus, be able to decode x, y
133 and states of 3 buttons correctly.
135 Device drivers may offer operation levels higher than one.
136 Refer to manual pages of individual drivers for details.
140 commands are defined for the mouse drivers.
141 The degree of support
142 varies from one driver to another.
143 This section gives general
144 description of the commands.
145 Refer to manual pages of individual drivers for specific details.
147 .Bl -tag -width MOUSE -compact
148 .It Dv MOUSE_GETLEVEL Ar int *level
149 .It Dv MOUSE_SETLEVEL Ar int *level
150 These commands manipulate the operation level of the mouse driver.
152 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
153 Returns the hardware information of the attached device in the following
156 field, the device driver may not always fill the structure with correct
158 Consult manual pages of individual drivers for details of support.
160 typedef struct mousehw {
161 int buttons; /* number of buttons */
162 int iftype; /* I/F type */
163 int type; /* mouse/track ball/pad... */
164 int model; /* I/F dependent model ID */
165 int hwid; /* I/F dependent hardware ID */
171 field holds the number of buttons detected by the driver.
173 may put an arbitrary value, such as two, in this field, if it cannot
174 determine the exact number.
178 is the type of interface:
179 .Dv MOUSE_IF_SERIAL ,
181 .Dv MOUSE_IF_INPORT ,
184 .Dv MOUSE_IF_SYSMOUSE
186 .Dv MOUSE_IF_UNKNOWN .
190 tells the device type:
192 .Dv MOUSE_TRACKBALL ,
201 .Dv MOUSE_MODEL_GENERIC
208 is the ID value returned by the pointing device.
210 depend on the interface type; refer to the manual page of
211 specific mouse drivers for possible values.
213 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
214 The command reports the current operation parameters of the mouse driver.
216 typedef struct mousemode {
217 int protocol; /* MOUSE_PROTO_XXX */
218 int rate; /* report rate (per sec) */
219 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
220 int accelfactor; /* acceleration factor */
221 int level; /* driver operation level */
222 int packetsize; /* the length of the data packet */
223 unsigned char syncmask[2]; /* sync. bits */
229 field tells the format in which the device status is returned
230 when the mouse data is read by the user program.
237 field is the status report rate (reports/sec) at which the device will send
238 movement reports to the host computer.
239 -1 if unknown or not applicable.
243 field holds a value specifying resolution of the pointing device.
244 It is a positive value or one of
250 field holds a value to control acceleration feature.
251 It must be zero or greater.
252 If it is zero, acceleration is disabled.
256 field tells the length of the fixed-size data packet or the length
257 of the fixed part of the variable-length packet.
258 The size depends on the interface type, the device type and model, the
259 protocol and the operation level of the driver.
263 holds a bit mask and pattern to detect the first byte of the
266 is the bit mask to be ANDed with a byte.
267 If the result is equal to
269 the byte is likely to be the first byte of the data packet.
270 Note that this method of detecting the first byte is not 100% reliable,
271 thus, should be taken only as an advisory measure.
273 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
274 The command changes the current operation parameters of the mouse driver
284 Setting values in the other field does not generate
285 error and has no effect.
287 If you do not want to change the current setting of a field, put -1
289 You may also put zero in
293 and the default value for the fields will be selected.
295 .It Dv MOUSE_READDATA Ar mousedata_t *data
296 The command reads the raw data from the device.
298 typedef struct mousedata {
299 int len; /* # of data in the buffer */
300 int buf[16]; /* data buffer */
304 The calling process must fill the
306 field with the number of bytes to be read into the buffer.
307 This command may not be supported by all drivers.
309 .It Dv MOUSE_READSTATE Ar mousedata_t *state
310 The command reads the raw state data from the device.
311 It uses the same structure as above.
312 This command may not be supported by all drivers.
314 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
315 The command returns the current state of buttons and
316 movement counts in the following structure.
318 typedef struct mousestatus {
319 int flags; /* state change flags */
320 int button; /* button status */
321 int obutton; /* previous button status */
322 int dx; /* x movement */
323 int dy; /* y movement */
324 int dz; /* z movement */
332 fields hold the current and the previous state of the mouse buttons.
333 When a button is pressed, the corresponding bit is set.
334 The mouse drivers may support up to 31 buttons with the bit 0 through 31.
335 Few button bits are defined as
336 .Dv MOUSE_BUTTON1DOWN
338 .Dv MOUSE_BUTTON8DOWN .
339 The first three buttons correspond to left, middle and right buttons.
341 If the state of the button has changed since the last
343 call, the corresponding bit in the
346 If the mouse has moved since the last call, the
350 field will also be set.
352 The other fields hold movement counts since the last
355 The internal counters will be reset after every call to this
359 .Bl -tag -width /dev/sysmouseXX -compact
377 This manual page was written by
378 .An Kazutaka Yokota Aq Mt yokota@FreeBSD.org .