Commit | Line | Data |
---|---|---|
984263bc MD |
1 | .\" Copyright (c) 1997 |
2 | .\" John-Mark Gurney. All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. Neither the name of the author nor the names of any co-contributors | |
13 | .\" may be used to endorse or promote products derived from this software | |
14 | .\" without specific prior written permission. | |
15 | .\" | |
16 | .\" THIS SOFTWARE IS PROVIDED BY John-Mark Gurney AND CONTRIBUTORS ``AS IS'' AND | |
17 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
18 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
19 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |
20 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
21 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
22 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
23 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
24 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
25 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
26 | .\" SUCH DAMAGE. | |
27 | .\" | |
28 | .\" $FreeBSD: src/share/man/man4/sysmouse.4,v 1.12.2.5 2001/12/17 11:30:12 ru Exp $ | |
29 | .\" | |
30 | .Dd December 3, 1997 | |
31 | .Dt SYSMOUSE 4 | |
32 | .Os | |
33 | .Sh NAME | |
34 | .Nm sysmouse | |
35 | .\" .Nd supplies mouse data from syscons for other applications | |
36 | .Nd virtualized mouse driver | |
37 | .Sh SYNOPSIS | |
62770245 | 38 | .In sys/mouse.h |
984263bc MD |
39 | .In machine/console.h |
40 | .Sh DESCRIPTION | |
41 | The console driver, in conjunction with the mouse daemon | |
42 | .Xr moused 8 , | |
43 | supplies mouse data to the user process in the standardized way via the | |
44 | .Nm | |
45 | driver. | |
46 | This arrangement makes it possible for the console and the user process | |
47 | (such as the | |
48 | .Tn X\ Window System ) | |
49 | to share the mouse. | |
50 | .Pp | |
51 | The user process which wants to utilize mouse operation simply opens | |
52 | .Pa /dev/sysmouse | |
53 | with a | |
54 | .Xr open 2 | |
55 | call and reads | |
56 | mouse data from the device via | |
57 | .Xr read 2 . | |
58 | Make sure that | |
59 | .Xr moused 8 | |
60 | is running, otherwise the user process won't see any data coming from | |
61 | the mouse. | |
984263bc MD |
62 | .Ss Operation Levels |
63 | The | |
64 | .Nm | |
65 | driver has two levels of operation. | |
66 | The current operation level can be referred to and changed via ioctl calls. | |
67 | .Pp | |
68 | The level zero, the basic level, is the lowest level at which the driver | |
69 | offers the basic service to user programs. | |
70 | The | |
71 | .Nm | |
72 | driver | |
73 | provides horizontal and vertical movement of the mouse | |
74 | and state of up to three buttons in the | |
75 | .Tn MouseSystems | |
76 | format 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. To obtain the full horizontal movement count, add | |
103 | the byte 2 and 4. | |
104 | .It Byte 5 | |
105 | The second half of the vertical movement count in two's complement; | |
106 | -128 through 127. To obtain the full vertical movement count, add | |
107 | the byte 3 and 5. | |
108 | .El | |
109 | .Pp | |
110 | At the level one, the extended level, mouse data is encoded | |
111 | in the standard format | |
112 | .Dv MOUSE_PROTO_SYSMOUSE | |
113 | as defined in | |
114 | .Xr mouse 4 . | |
115 | .\" .Ss Acceleration | |
116 | .\" The | |
117 | .\" .Nm | |
118 | .\" driver can somewhat `accelerate' the movement of the pointing device. | |
119 | .\" The faster you move the device, the further the pointer | |
120 | .\" travels on the screen. | |
121 | .\" The driver has an internal variable which governs the effect of | |
122 | .\" the acceleration. Its value can be modified via the driver flag | |
123 | .\" or via an ioctl call. | |
124 | .Sh IOCTLS | |
125 | This section describes two classes of | |
126 | .Xr ioctl 2 | |
127 | commands: | |
128 | commands for the | |
129 | .Nm | |
130 | driver itself, and commands for the console and the console control drivers. | |
131 | .Ss Sysmouse Ioctls | |
132 | There are a few commands for mouse drivers. | |
133 | General description of the commands is given in | |
134 | .Xr mouse 4 . | |
135 | Following are the features specific to the | |
136 | .Nm | |
137 | driver. | |
138 | .Pp | |
139 | .Bl -tag -width MOUSE -compact | |
140 | .It Dv MOUSE_GETLEVEL Ar int *level | |
141 | .It Dv MOUSE_SETLEVEL Ar int *level | |
142 | These commands manipulate the operation level of the mouse driver. | |
143 | .Pp | |
144 | .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw | |
145 | Returns the hardware information of the attached device in the following | |
146 | structure. Only the | |
cb803e4d | 147 | .Fa iftype |
984263bc MD |
148 | field is guaranteed to be filled with the correct value in the current |
149 | version of the | |
150 | .Nm | |
151 | driver. | |
152 | .Bd -literal | |
153 | typedef struct mousehw { | |
154 | int buttons; /* number of buttons */ | |
155 | int iftype; /* I/F type */ | |
156 | int type; /* mouse/track ball/pad... */ | |
157 | int model; /* I/F dependent model ID */ | |
158 | int hwid; /* I/F dependent hardware ID */ | |
159 | } mousehw_t; | |
160 | .Ed | |
161 | .Pp | |
162 | The | |
cb803e4d | 163 | .Fa buttons |
984263bc MD |
164 | field holds the number of buttons detected by the driver. |
165 | .Pp | |
166 | The | |
cb803e4d | 167 | .Fa iftype |
984263bc MD |
168 | is always |
169 | .Dv MOUSE_IF_SYSMOUSE . | |
170 | .Pp | |
171 | The | |
cb803e4d | 172 | .Fa type |
984263bc MD |
173 | tells the device type: |
174 | .Dv MOUSE_MOUSE , | |
175 | .Dv MOUSE_TRACKBALL , | |
176 | .Dv MOUSE_STICK , | |
177 | .Dv MOUSE_PAD , | |
178 | or | |
179 | .Dv MOUSE_UNKNOWN . | |
180 | .Pp | |
181 | The | |
cb803e4d | 182 | .Fa model |
984263bc MD |
183 | is always |
184 | .Dv MOUSE_MODEL_GENERIC | |
185 | at the operation level 0. | |
186 | It may be | |
187 | .Dv MOUSE_MODEL_GENERIC | |
188 | or one of | |
189 | .Dv MOUSE_MODEL_XXX | |
190 | constants at higher operation levels. | |
191 | .Pp | |
192 | The | |
cb803e4d | 193 | .Fa hwid |
984263bc MD |
194 | is always zero. |
195 | .Pp | |
196 | .It Dv MOUSE_GETMODE Ar mousemode_t *mode | |
197 | The command gets the current operation parameters of the mouse | |
198 | driver. | |
199 | .Bd -literal | |
200 | typedef struct mousemode { | |
201 | int protocol; /* MOUSE_PROTO_XXX */ | |
202 | int rate; /* report rate (per sec) */ | |
203 | int resolution; /* MOUSE_RES_XXX, -1 if unknown */ | |
204 | int accelfactor; /* acceleration factor */ | |
205 | int level; /* driver operation level */ | |
206 | int packetsize; /* the length of the data packet */ | |
207 | unsigned char syncmask[2]; /* sync. bits */ | |
208 | } mousemode_t; | |
209 | .Ed | |
210 | .Pp | |
211 | The | |
cb803e4d | 212 | .Fa protocol |
984263bc MD |
213 | field tells the format in which the device status is returned |
214 | when the mouse data is read by the user program. | |
215 | It is | |
216 | .Dv MOUSE_PROTO_MSC | |
217 | at the operation level zero. | |
218 | .Dv MOUSE_PROTO_SYSMOUSE | |
219 | at the operation level one. | |
220 | .Pp | |
221 | The | |
cb803e4d | 222 | .Fa rate |
984263bc MD |
223 | is always set to -1. |
224 | .Pp | |
225 | The | |
cb803e4d | 226 | .Fa resolution |
984263bc MD |
227 | is always set to -1. |
228 | .Pp | |
229 | The | |
cb803e4d | 230 | .Fa accelfactor |
984263bc MD |
231 | is always 0. |
232 | .Pp | |
233 | The | |
cb803e4d | 234 | .Fa packetsize |
984263bc MD |
235 | field specifies the length of the data packet. |
236 | It depends on the | |
237 | operation level. | |
238 | .Pp | |
239 | .Bl -tag -width level_0__ -compact | |
240 | .It Em level 0 | |
241 | 5 bytes | |
242 | .It Em level 1 | |
243 | 8 bytes | |
244 | .El | |
245 | .Pp | |
246 | The array | |
cb803e4d | 247 | .Fa syncmask |
984263bc MD |
248 | holds a bit mask and pattern to detect the first byte of the |
249 | data packet. | |
cb803e4d | 250 | .Fa syncmask Ns Bq 0 |
984263bc MD |
251 | is the bit mask to be ANDed with a byte. |
252 | If the result is equal to | |
cb803e4d | 253 | .Fa syncmask Ns Bq 1 , |
984263bc MD |
254 | the byte is likely to be the first byte of the data packet. |
255 | Note that this method of detecting the first byte is not 100% reliable; | |
256 | thus, it should be taken only as an advisory measure. | |
257 | .Pp | |
258 | .It Dv MOUSE_SETMODE Ar mousemode_t *mode | |
259 | The command changes the current operation parameters of the mouse driver | |
260 | as specified in | |
261 | .Ar mode . | |
262 | Only | |
cb803e4d | 263 | .Fa level |
984263bc MD |
264 | may be modifiable. |
265 | Setting values in the other field does not generate | |
266 | error and has no effect. | |
267 | .\" .Pp | |
268 | .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars | |
269 | .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars | |
270 | .\" These commands are not supported by the | |
271 | .\" .Nm | |
272 | .\" driver. | |
273 | .Pp | |
274 | .It Dv MOUSE_READDATA Ar mousedata_t *data | |
275 | .It Dv MOUSE_READSTATE Ar mousedata_t *state | |
276 | These commands are not supported by the | |
277 | .Nm | |
278 | driver. | |
279 | .Pp | |
280 | .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status | |
281 | The command returns the current state of buttons and | |
282 | movement counts in the structure as defined in | |
283 | .Xr mouse 4 . | |
284 | .El | |
285 | .Ss Console and Consolectl Ioctls | |
286 | The user process issues console | |
287 | .Fn ioctl | |
288 | calls to the current virtual console in order to control | |
289 | the mouse pointer. | |
290 | The console | |
291 | .Fn ioctl | |
292 | also provides a method for the user process to receive a | |
293 | .Xr signal 3 | |
294 | when a button is pressed. | |
295 | .Pp | |
296 | The mouse daemon | |
297 | .Xr moused 8 | |
298 | uses | |
299 | .Fn ioctl | |
300 | calls to the console control device | |
301 | .Pa /dev/consolectl | |
302 | to inform the console of mouse actions including mouse movement | |
303 | and button status. | |
304 | .Pp | |
305 | Both classes of | |
306 | .Fn ioctl | |
307 | commands are defined as | |
308 | .Dv CONS_MOUSECTL | |
309 | which takes the following argument. | |
310 | .Bd -literal | |
311 | struct mouse_info { | |
312 | int operation; | |
313 | union { | |
314 | struct mouse_data data; | |
315 | struct mouse_mode mode; | |
316 | struct mouse_event event; | |
317 | } u; | |
318 | }; | |
319 | .Ed | |
320 | .Pp | |
321 | .Bl -tag -width operation -compact | |
cb803e4d | 322 | .It Fa operation |
984263bc MD |
323 | This can be one of |
324 | .Pp | |
325 | .Bl -tag -width MOUSE_MOVEABS -compact | |
326 | .It Dv MOUSE_SHOW | |
327 | Enables and displays mouse cursor. | |
328 | .It Dv MOUSE_HIDE | |
329 | Disables and hides mouse cursor. | |
330 | .It Dv MOUSE_MOVEABS | |
331 | Moves mouse cursor to position supplied in | |
cb803e4d | 332 | .Fa u.data . |
984263bc MD |
333 | .It Dv MOUSE_MOVEREL |
334 | Adds position supplied in | |
cb803e4d | 335 | .Fa u.data |
984263bc MD |
336 | to current position. |
337 | .It Dv MOUSE_GETINFO | |
338 | Returns current mouse position in the current virtual console | |
339 | and button status in | |
cb803e4d | 340 | .Fa u.data . |
984263bc MD |
341 | .It Dv MOUSE_MODE |
342 | This sets the | |
343 | .Xr signal 3 | |
344 | to be delivered to the current process when a button is pressed. | |
345 | The signal to be delivered is set in | |
cb803e4d | 346 | .Fa u.mode . |
984263bc MD |
347 | .El |
348 | .Pp | |
349 | The above operations are for virtual consoles. | |
350 | The operations defined | |
351 | below are for the console control device and are used by | |
352 | .Xr moused 8 | |
353 | to pass mouse data to the console driver. | |
354 | .Pp | |
355 | .Bl -tag -width MOUSE_MOVEABS -compact | |
356 | .It Dv MOUSE_ACTION | |
9567d797 | 357 | .It Dv MOUSE_MOTION_EVENT |
984263bc | 358 | These operations take the information in |
cb803e4d | 359 | .Fa u.data |
984263bc MD |
360 | and act upon it. Mouse data will be sent to the |
361 | .Nm | |
362 | driver if it is open. | |
363 | .Dv MOUSE_ACTION | |
364 | also processes button press actions and sends signal to the process if | |
365 | requested or performs cut and paste operations | |
366 | if the current console is a text interface. | |
9567d797 | 367 | .It Dv MOUSE_BUTTON_EVENT |
cb803e4d | 368 | .Fa u.data |
984263bc MD |
369 | specifies a button and its click count. |
370 | The console driver will | |
371 | use this information for signal delivery if requested or | |
372 | for cut and paste operations if the console is in text mode. | |
373 | .El | |
374 | .Pp | |
9567d797 | 375 | .Dv MOUSE_MOTION_EVENT |
984263bc | 376 | and |
9567d797 | 377 | .Dv MOUSE_BUTTON_EVENT |
984263bc MD |
378 | are newer interface and are designed to be used together. |
379 | They are intended to replace functions performed by | |
380 | .Dv MOUSE_ACTION | |
381 | alone. | |
382 | .Pp | |
cb803e4d | 383 | .It Fa u |
984263bc MD |
384 | This union is one of |
385 | .Pp | |
386 | .Bl -tag -width data -compact | |
cb803e4d | 387 | .It Fa data |
984263bc MD |
388 | .Bd -literal |
389 | struct mouse_data { | |
390 | int x; | |
391 | int y; | |
392 | int z; | |
393 | int buttons; | |
394 | }; | |
395 | .Ed | |
396 | .Pp | |
cb803e4d SW |
397 | .Fa x , |
398 | .Fa y | |
984263bc | 399 | and |
cb803e4d | 400 | .Fa z |
984263bc | 401 | represent movement of the mouse along respective directions. |
cb803e4d | 402 | .Fa buttons |
984263bc MD |
403 | tells the state of buttons. |
404 | It encodes up to 31 buttons in the bit 0 though | |
405 | the bit 30. If a button is held down, the corresponding bit is set. | |
406 | .Pp | |
cb803e4d | 407 | .It Fa mode |
984263bc MD |
408 | .Bd -literal |
409 | struct mouse_mode { | |
410 | int mode; | |
411 | int signal; | |
412 | }; | |
413 | .Ed | |
414 | .Pp | |
415 | The | |
cb803e4d | 416 | .Fa signal |
984263bc MD |
417 | field specifies the signal to be delivered to the process. |
418 | It must be | |
419 | one of the values defined in | |
44cb301e | 420 | .In signal.h . |
984263bc | 421 | The |
cb803e4d | 422 | .Fa mode |
984263bc MD |
423 | field is currently unused. |
424 | .Pp | |
cb803e4d | 425 | .It Fa event |
984263bc MD |
426 | .Bd -literal |
427 | struct mouse_event { | |
428 | int id; | |
429 | int value; | |
430 | }; | |
431 | .Ed | |
432 | .Pp | |
433 | The | |
cb803e4d | 434 | .Fa id |
984263bc | 435 | field specifies a button number as in |
cb803e4d | 436 | .Fa u.data.buttons . |
984263bc MD |
437 | Only one bit/button is set. |
438 | The | |
cb803e4d | 439 | .Fa value |
984263bc MD |
440 | field |
441 | holds the click count: the number of times the user has clicked the button | |
442 | successively. | |
984263bc MD |
443 | .El |
444 | .El | |
445 | .Sh FILES | |
446 | .Bl -tag -width /dev/consolectl -compact | |
447 | .It Pa /dev/consolectl | |
448 | device to control the console | |
449 | .It Pa /dev/sysmouse | |
450 | virtualized mouse driver | |
451 | .It Pa /dev/ttyv%d | |
452 | virtual consoles | |
453 | .El | |
454 | .Sh SEE ALSO | |
455 | .Xr vidcontrol 1 , | |
456 | .Xr ioctl 2 , | |
457 | .Xr signal 3 , | |
458 | .Xr mouse 4 , | |
459 | .Xr moused 8 | |
460 | .Sh HISTORY | |
461 | The | |
462 | .Nm | |
463 | manual page example first appeared in | |
464 | .Fx 2.2 . | |
465 | .Sh AUTHORS | |
466 | .An -nosplit | |
467 | This | |
468 | manual page was written by | |
e18a87e3 | 469 | .An John-Mark Gurney Aq Mt gurney_j@efn.org |
984263bc | 470 | and |
e18a87e3 | 471 | .An Kazutaka Yokota Aq Mt yokota@FreeBSD.org . |