1 |
.\" $MidnightBSD$ |
2 |
.\" |
3 |
.\" Copyright (c) 1997 |
4 |
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp> |
5 |
.\" All rights reserved. |
6 |
.\" |
7 |
.\" Redistribution and use in source and binary forms, with or without |
8 |
.\" modification, are permitted provided that the following conditions |
9 |
.\" are met: |
10 |
.\" 1. Redistributions of source code must retain the above copyright |
11 |
.\" notice, this list of conditions and the following disclaimer as |
12 |
.\" the first lines of this file unmodified. |
13 |
.\" 2. Redistributions in binary form must reproduce the above copyright |
14 |
.\" notice, this list of conditions and the following disclaimer in the |
15 |
.\" documentation and/or other materials provided with the distribution. |
16 |
.\" |
17 |
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR |
18 |
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
19 |
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. |
20 |
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, |
21 |
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT |
22 |
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
23 |
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
24 |
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
25 |
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
26 |
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
27 |
.\" |
28 |
.\" $FreeBSD: stable/10/share/man/man4/mouse.4 244040 2012-12-08 22:16:36Z eadler $ |
29 |
.\" |
30 |
.Dd December 3, 1997 |
31 |
.Dt MOUSE 4 |
32 |
.Os |
33 |
.Sh NAME |
34 |
.Nm mouse |
35 |
.Nd mouse and pointing device drivers |
36 |
.Sh SYNOPSIS |
37 |
.In sys/mouse.h |
38 |
.Sh DESCRIPTION |
39 |
The mouse drivers |
40 |
.Xr mse 4 , |
41 |
.Xr psm 4 , |
42 |
.Xr ums 4 |
43 |
and |
44 |
.Xr sysmouse 4 |
45 |
provide user programs with movement and button state information of the mouse. |
46 |
Currently there are specific device drivers for bus, InPort, PS/2, and USB mice. |
47 |
The serial mouse is not directly supported by a dedicated driver, but |
48 |
it is accessible via the serial device driver or via |
49 |
.Xr moused 8 |
50 |
and |
51 |
.Xr sysmouse 4 . |
52 |
.Pp |
53 |
The user program simply opens a mouse device with a |
54 |
.Xr open 2 |
55 |
call and reads |
56 |
mouse data from the device via |
57 |
.Xr read 2 . |
58 |
Movement and button states are usually encoded in fixed-length data packets. |
59 |
Some mouse devices may send data in variable length of packets. |
60 |
Actual protocol (data format) used by each driver differs widely. |
61 |
.Pp |
62 |
The mouse drivers may have ``non-blocking'' attribute which will make |
63 |
the driver return immediately if mouse data is not available. |
64 |
.Pp |
65 |
Mouse device drivers often offer several levels of operation. |
66 |
The current operation level can be examined and changed via |
67 |
.Xr ioctl 2 |
68 |
commands. |
69 |
The level zero is the lowest level at which the driver offers the basic |
70 |
service to user programs. |
71 |
Most drivers provide horizontal and vertical movement of the mouse |
72 |
and state of up to three buttons at this level. |
73 |
At the level one, if supported by the driver, mouse data is encoded |
74 |
in the standard format |
75 |
.Dv MOUSE_PROTO_SYSMOUSE |
76 |
as follows: |
77 |
.Pp |
78 |
.Bl -tag -width Byte_1 -compact |
79 |
.It Byte 1 |
80 |
.Bl -tag -width bit_7 -compact |
81 |
.It bit 7 |
82 |
Always one. |
83 |
.It bit 6..3 |
84 |
Always zero. |
85 |
.It bit 2 |
86 |
Left button status; cleared if pressed, otherwise set. |
87 |
.It bit 1 |
88 |
Middle button status; cleared if pressed, otherwise set. |
89 |
Always one, |
90 |
if the device does not have the middle button. |
91 |
.It bit 0 |
92 |
Right button status; cleared if pressed, otherwise set. |
93 |
.El |
94 |
.It Byte 2 |
95 |
The first half of horizontal movement count in two's complement; |
96 |
-128 through 127. |
97 |
.It Byte 3 |
98 |
The first half of vertical movement count in two's complement; |
99 |
-128 through 127. |
100 |
.It Byte 4 |
101 |
The second half of the horizontal movement count in two's complement; |
102 |
-128 through 127. |
103 |
To obtain the full horizontal movement count, add |
104 |
the byte 2 and 4. |
105 |
.It Byte 5 |
106 |
The second half of the vertical movement count in two's complement; |
107 |
-128 through 127. |
108 |
To obtain the full vertical movement count, add |
109 |
the byte 3 and 5. |
110 |
.It Byte 6 |
111 |
The bit 7 is always zero. |
112 |
The lower 7 bits encode the first half of |
113 |
Z axis movement count in two's complement; -64 through 63. |
114 |
.It Byte 7 |
115 |
The bit 7 is always zero. |
116 |
The lower 7 bits encode the second half of |
117 |
the Z axis movement count in two's complement; -64 through 63. |
118 |
To obtain the full Z axis movement count, add the byte 6 and 7. |
119 |
.It Byte 8 |
120 |
The bit 7 is always zero. |
121 |
The bits 0 through 6 reflect the state |
122 |
of the buttons 4 through 10. |
123 |
If a button is pressed, the corresponding bit is cleared. |
124 |
Otherwise |
125 |
the bit is set. |
126 |
.El |
127 |
.Pp |
128 |
The first 5 bytes of this format is compatible with the MouseSystems |
129 |
format. |
130 |
The additional 3 bytes have their MSBs always set to zero. |
131 |
Thus, if the user program can interpret the MouseSystems data format and |
132 |
tries to find the first byte of the format by detecting the bit pattern |
133 |
10000xxxb, |
134 |
it will discard the additional bytes, thus, be able to decode x, y |
135 |
and states of 3 buttons correctly. |
136 |
.Pp |
137 |
Device drivers may offer operation levels higher than one. |
138 |
Refer to manual pages of individual drivers for details. |
139 |
.Sh IOCTLS |
140 |
The following |
141 |
.Xr ioctl 2 |
142 |
commands are defined for the mouse drivers. |
143 |
The degree of support |
144 |
varies from one driver to another. |
145 |
This section gives general |
146 |
description of the commands. |
147 |
Refer to manual pages of individual drivers for specific details. |
148 |
.Pp |
149 |
.Bl -tag -width MOUSE -compact |
150 |
.It Dv MOUSE_GETLEVEL Ar int *level |
151 |
.It Dv MOUSE_SETLEVEL Ar int *level |
152 |
These commands manipulate the operation level of the mouse driver. |
153 |
.Pp |
154 |
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw |
155 |
Returns the hardware information of the attached device in the following |
156 |
Except for the |
157 |
.Dv iftype |
158 |
field, the device driver may not always fill the structure with correct |
159 |
values. |
160 |
Consult manual pages of individual drivers for details of support. |
161 |
.Bd -literal |
162 |
typedef struct mousehw { |
163 |
int buttons; /* number of buttons */ |
164 |
int iftype; /* I/F type */ |
165 |
int type; /* mouse/track ball/pad... */ |
166 |
int model; /* I/F dependent model ID */ |
167 |
int hwid; /* I/F dependent hardware ID */ |
168 |
} mousehw_t; |
169 |
.Ed |
170 |
.Pp |
171 |
The |
172 |
.Dv buttons |
173 |
field holds the number of buttons detected by the driver. |
174 |
The driver |
175 |
may put an arbitrary value, such as two, in this field, if it cannot |
176 |
determine the exact number. |
177 |
.Pp |
178 |
The |
179 |
.Dv iftype |
180 |
is the type of interface: |
181 |
.Dv MOUSE_IF_SERIAL , |
182 |
.Dv MOUSE_IF_BUS , |
183 |
.Dv MOUSE_IF_INPORT , |
184 |
.Dv MOUSE_IF_PS2 , |
185 |
.Dv MOUSE_IF_USB , |
186 |
.Dv MOUSE_IF_SYSMOUSE |
187 |
or |
188 |
.Dv MOUSE_IF_UNKNOWN . |
189 |
.Pp |
190 |
The |
191 |
.Dv type |
192 |
tells the device type: |
193 |
.Dv MOUSE_MOUSE , |
194 |
.Dv MOUSE_TRACKBALL , |
195 |
.Dv MOUSE_STICK , |
196 |
.Dv MOUSE_PAD , |
197 |
or |
198 |
.Dv MOUSE_UNKNOWN . |
199 |
.Pp |
200 |
The |
201 |
.Dv model |
202 |
may be |
203 |
.Dv MOUSE_MODEL_GENERIC |
204 |
or one of |
205 |
.Dv MOUSE_MODEL_XXX |
206 |
constants. |
207 |
.Pp |
208 |
The |
209 |
.Dv hwid |
210 |
is the ID value returned by the pointing device. |
211 |
It |
212 |
depend on the interface type; refer to the manual page of |
213 |
specific mouse drivers for possible values. |
214 |
.Pp |
215 |
.It Dv MOUSE_GETMODE Ar mousemode_t *mode |
216 |
The command reports the current operation parameters of the mouse driver. |
217 |
.Bd -literal |
218 |
typedef struct mousemode { |
219 |
int protocol; /* MOUSE_PROTO_XXX */ |
220 |
int rate; /* report rate (per sec) */ |
221 |
int resolution; /* MOUSE_RES_XXX, -1 if unknown */ |
222 |
int accelfactor; /* acceleration factor */ |
223 |
int level; /* driver operation level */ |
224 |
int packetsize; /* the length of the data packet */ |
225 |
unsigned char syncmask[2]; /* sync. bits */ |
226 |
} mousemode_t; |
227 |
.Ed |
228 |
.Pp |
229 |
The |
230 |
.Dv protocol |
231 |
field tells the format in which the device status is returned |
232 |
when the mouse data is read by the user program. |
233 |
It is one of |
234 |
.Dv MOUSE_PROTO_XXX |
235 |
constants. |
236 |
.Pp |
237 |
The |
238 |
.Dv rate |
239 |
field is the status report rate (reports/sec) at which the device will send |
240 |
movement reports to the host computer. |
241 |
-1 if unknown or not applicable. |
242 |
.Pp |
243 |
The |
244 |
.Dv resolution |
245 |
field holds a value specifying resolution of the pointing device. |
246 |
It is a positive value or one of |
247 |
.Dv MOUSE_RES_XXX |
248 |
constants. |
249 |
.Pp |
250 |
The |
251 |
.Dv accelfactor |
252 |
field holds a value to control acceleration feature. |
253 |
It must be zero or greater. |
254 |
If it is zero, acceleration is disabled. |
255 |
.Pp |
256 |
The |
257 |
.Dv packetsize |
258 |
field tells the length of the fixed-size data packet or the length |
259 |
of the fixed part of the variable-length packet. |
260 |
The size depends on the interface type, the device type and model, the |
261 |
protocol and the operation level of the driver. |
262 |
.Pp |
263 |
The array |
264 |
.Dv syncmask |
265 |
holds a bit mask and pattern to detect the first byte of the |
266 |
data packet. |
267 |
.Dv syncmask[0] |
268 |
is the bit mask to be ANDed with a byte. |
269 |
If the result is equal to |
270 |
.Dv syncmask[1] , |
271 |
the byte is likely to be the first byte of the data packet. |
272 |
Note that this method of detecting the first byte is not 100% reliable, |
273 |
thus, should be taken only as an advisory measure. |
274 |
.Pp |
275 |
.It Dv MOUSE_SETMODE Ar mousemode_t *mode |
276 |
The command changes the current operation parameters of the mouse driver |
277 |
as specified in |
278 |
.Ar mode . |
279 |
Only |
280 |
.Dv rate , |
281 |
.Dv resolution , |
282 |
.Dv level |
283 |
and |
284 |
.Dv accelfactor |
285 |
may be modifiable. |
286 |
Setting values in the other field does not generate |
287 |
error and has no effect. |
288 |
.Pp |
289 |
If you do not want to change the current setting of a field, put -1 |
290 |
there. |
291 |
You may also put zero in |
292 |
.Dv resolution |
293 |
and |
294 |
.Dv rate , |
295 |
and the default value for the fields will be selected. |
296 |
.\" .Pp |
297 |
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars |
298 |
.\" Get internal variables of the mouse driver. |
299 |
.\" The variables which can be manipulated through these commands |
300 |
.\" are specific to each driver. |
301 |
.\" This command may not be supported by all drivers. |
302 |
.\" .Bd -literal |
303 |
.\" typedef struct mousevar { |
304 |
.\" int var[16]; /* internal variables */ |
305 |
.\" } mousevar_t; |
306 |
.\" .Ed |
307 |
.\" .Pp |
308 |
.\" If the commands are supported, the first element of the array is |
309 |
.\" filled with a signature value. |
310 |
.\" Apart from the signature data, there is currently no standard concerning |
311 |
.\" the other elements of the buffer. |
312 |
.\" .Pp |
313 |
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars |
314 |
.\" Get internal variables of the mouse driver. |
315 |
.\" The first element of the array must be a signature value. |
316 |
.\" This command may not be supported by all drivers. |
317 |
.Pp |
318 |
.It Dv MOUSE_READDATA Ar mousedata_t *data |
319 |
The command reads the raw data from the device. |
320 |
.Bd -literal |
321 |
typedef struct mousedata { |
322 |
int len; /* # of data in the buffer */ |
323 |
int buf[16]; /* data buffer */ |
324 |
} mousedata_t; |
325 |
.Ed |
326 |
.Pp |
327 |
The calling process must fill the |
328 |
.Dv len |
329 |
field with the number of bytes to be read into the buffer. |
330 |
This command may not be supported by all drivers. |
331 |
.Pp |
332 |
.It Dv MOUSE_READSTATE Ar mousedata_t *state |
333 |
The command reads the raw state data from the device. |
334 |
It uses the same structure as above. |
335 |
This command may not be supported by all drivers. |
336 |
.Pp |
337 |
.It Dv MOUSE_GETSTATUS Ar mousestatus_t *status |
338 |
The command returns the current state of buttons and |
339 |
movement counts in the following structure. |
340 |
.Bd -literal |
341 |
typedef struct mousestatus { |
342 |
int flags; /* state change flags */ |
343 |
int button; /* button status */ |
344 |
int obutton; /* previous button status */ |
345 |
int dx; /* x movement */ |
346 |
int dy; /* y movement */ |
347 |
int dz; /* z movement */ |
348 |
} mousestatus_t; |
349 |
.Ed |
350 |
.Pp |
351 |
The |
352 |
.Dv button |
353 |
and |
354 |
.Dv obutton |
355 |
fields hold the current and the previous state of the mouse buttons. |
356 |
When a button is pressed, the corresponding bit is set. |
357 |
The mouse drivers may support up to 31 buttons with the bit 0 through 31. |
358 |
Few button bits are defined as |
359 |
.Dv MOUSE_BUTTON1DOWN |
360 |
through |
361 |
.Dv MOUSE_BUTTON8DOWN . |
362 |
The first three buttons correspond to left, middle and right buttons. |
363 |
.Pp |
364 |
If the state of the button has changed since the last |
365 |
.Dv MOUSE_GETSTATUS |
366 |
call, the corresponding bit in the |
367 |
.Dv flags |
368 |
field will be set. |
369 |
If the mouse has moved since the last call, the |
370 |
.Dv MOUSE_POSCHANGED |
371 |
bit in the |
372 |
.Dv flags |
373 |
field will also be set. |
374 |
.Pp |
375 |
The other fields hold movement counts since the last |
376 |
.Dv MOUSE_GETSTATUS |
377 |
call. |
378 |
The internal counters will be reset after every call to this |
379 |
command. |
380 |
.El |
381 |
.Sh FILES |
382 |
.Bl -tag -width /dev/sysmouseXX -compact |
383 |
.It Pa /dev/cuau%d |
384 |
serial ports |
385 |
.It Pa /dev/mse%d |
386 |
bus and InPort mouse device |
387 |
.It Pa /dev/psm%d |
388 |
PS/2 mouse device |
389 |
.It Pa /dev/sysmouse |
390 |
virtual mouse device |
391 |
.It Pa /dev/ums%d |
392 |
USB mouse device |
393 |
.El |
394 |
.Sh SEE ALSO |
395 |
.Xr ioctl 2 , |
396 |
.Xr mse 4 , |
397 |
.Xr psm 4 , |
398 |
.Xr sysmouse 4 , |
399 |
.Xr ums 4 , |
400 |
.Xr moused 8 |
401 |
.\".Sh HISTORY |
402 |
.Sh AUTHORS |
403 |
This manual page was written by |
404 |
.An Kazutaka Yokota Aq yokota@FreeBSD.org . |