| blob | 96547bcfae781b442b540d160e92059651dca01e |
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$
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
38 .In sys/mouse.h
39 .In sys/consio.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 will not see any data coming from
61 the mouse.
62 .Pp
63 .Ss Operation Levels
64 The
65 .Nm
66 driver has two levels of operation.
67 The current operation level can be referred to and changed via ioctl calls.
68 .Pp
69 The level zero, the basic level, is the lowest level at which the driver
70 offers the basic service to user programs.
71 The
72 .Nm
73 driver
74 provides horizontal and vertical movement of the mouse
75 and state of up to three buttons in the
76 .Tn MouseSystems
77 format as follows.
78 .Pp
79 .Bl -tag -width Byte_1 -compact
80 .It Byte 1
81 .Bl -tag -width bit_7 -compact
82 .It bit 7
83 Always one.
84 .It bit 6..3
85 Always zero.
86 .It bit 2
87 Left button status; cleared if pressed, otherwise set.
88 .It bit 1
89 Middle button status; cleared if pressed, otherwise set.
90 Always one,
91 if the device does not have the middle button.
92 .It bit 0
93 Right button status; cleared if pressed, otherwise set.
94 .El
95 .It Byte 2
96 The first half of horizontal movement count in two's complement;
97 -128 through 127.
98 .It Byte 3
99 The first half of vertical movement count in two's complement;
100 -128 through 127.
101 .It Byte 4
102 The second half of the horizontal movement count in two's complement;
103 -128 through 127.
104 To obtain the full horizontal movement count, add
105 the byte 2 and 4.
106 .It Byte 5
107 The second half of the vertical movement count in two's complement;
108 -128 through 127.
109 To obtain the full vertical movement count, add
110 the byte 3 and 5.
111 .El
112 .Pp
113 At the level one, the extended level, mouse data is encoded
114 in the standard format
115 .Dv MOUSE_PROTO_SYSMOUSE
116 as defined in
117 .Xr mouse 4 .
118 .\" .Ss Acceleration
119 .\" The
120 .\" .Nm
121 .\" driver can somewhat `accelerate' the movement of the pointing device.
122 .\" The faster you move the device, the further the pointer
123 .\" travels on the screen.
124 .\" The driver has an internal variable which governs the effect of
125 .\" the acceleration. Its value can be modified via the driver flag
126 .\" or via an ioctl call.
127 .Sh IOCTLS
128 This section describes two classes of
129 .Xr ioctl 2
130 commands:
131 commands for the
132 .Nm
133 driver itself, and commands for the console and the console control drivers.
134 .Ss Sysmouse Ioctls
135 There are a few commands for mouse drivers.
136 General description of the commands is given in
137 .Xr mouse 4 .
138 Following are the features specific to the
139 .Nm
140 driver.
141 .Pp
142 .Bl -tag -width MOUSE -compact
143 .It Dv MOUSE_GETLEVEL Ar int *level
144 .It Dv MOUSE_SETLEVEL Ar int *level
145 These commands manipulate the operation level of the mouse driver.
146 .Pp
147 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
148 Returns the hardware information of the attached device in the following
149 structure.
150 Only the
151 .Dv iftype
152 field is guaranteed to be filled with the correct value in the current
153 version of the
154 .Nm
155 driver.
156 .Bd -literal
157 typedef struct mousehw {
158 int buttons; /* number of buttons */
159 int iftype; /* I/F type */
160 int type; /* mouse/track ball/pad... */
161 int model; /* I/F dependent model ID */
162 int hwid; /* I/F dependent hardware ID */
163 } mousehw_t;
164 .Ed
165 .Pp
166 The
167 .Dv buttons
168 field holds the number of buttons detected by the driver.
169 .Pp
170 The
171 .Dv iftype
172 is always
173 .Dv MOUSE_IF_SYSMOUSE .
174 .Pp
175 The
176 .Dv type
177 tells the device type:
178 .Dv MOUSE_MOUSE ,
179 .Dv MOUSE_TRACKBALL ,
180 .Dv MOUSE_STICK ,
181 .Dv MOUSE_PAD ,
182 or
183 .Dv MOUSE_UNKNOWN .
184 .Pp
185 The
186 .Dv model
187 is always
188 .Dv MOUSE_MODEL_GENERIC
189 at the operation level 0.
190 It may be
191 .Dv MOUSE_MODEL_GENERIC
192 or one of
193 .Dv MOUSE_MODEL_XXX
194 constants at higher operation levels.
195 .Pp
196 The
197 .Dv hwid
198 is always zero.
199 .Pp
200 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
201 The command gets the current operation parameters of the mouse
202 driver.
203 .Bd -literal
204 typedef struct mousemode {
205 int protocol; /* MOUSE_PROTO_XXX */
206 int rate; /* report rate (per sec) */
207 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
208 int accelfactor; /* acceleration factor */
209 int level; /* driver operation level */
210 int packetsize; /* the length of the data packet */
211 unsigned char syncmask[2]; /* sync. bits */
212 } mousemode_t;
213 .Ed
214 .Pp
215 The
216 .Dv protocol
217 field tells the format in which the device status is returned
218 when the mouse data is read by the user program.
219 It is
220 .Dv MOUSE_PROTO_MSC
221 at the operation level zero.
222 .Dv MOUSE_PROTO_SYSMOUSE
223 at the operation level one.
224 .Pp
225 The
226 .Dv rate
227 is always set to -1.
228 .Pp
229 The
230 .Dv resolution
231 is always set to -1.
232 .Pp
233 The
234 .Dv accelfactor
235 is always 0.
236 .Pp
237 The
238 .Dv packetsize
239 field specifies the length of the data packet.
240 It depends on the
241 operation level.
242 .Pp
243 .Bl -tag -width level_0__ -compact
244 .It Em level 0
245 5 bytes
246 .It Em level 1
247 8 bytes
248 .El
249 .Pp
250 The array
251 .Dv syncmask
252 holds a bit mask and pattern to detect the first byte of the
253 data packet.
254 .Dv syncmask[0]
255 is the bit mask to be ANDed with a byte.
256 If the result is equal to
257 .Dv syncmask[1] ,
258 the byte is likely to be the first byte of the data packet.
259 Note that this method of detecting the first byte is not 100% reliable;
260 thus, it should be taken only as an advisory measure.
261 .Pp
262 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
263 The command changes the current operation parameters of the mouse driver
264 as specified in
265 .Ar mode .
266 Only
267 .Dv level
268 may be modifiable.
269 Setting values in the other field does not generate
270 error and has no effect.
271 .\" .Pp
272 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
273 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
274 .\" These commands are not supported by the
275 .\" .Nm
276 .\" driver.
277 .Pp
278 .It Dv MOUSE_READDATA Ar mousedata_t *data
279 .It Dv MOUSE_READSTATE Ar mousedata_t *state
280 These commands are not supported by the
281 .Nm
282 driver.
283 .Pp
284 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
285 The command returns the current state of buttons and
286 movement counts in the structure as defined in
287 .Xr mouse 4 .
288 .El
289 .Ss Console and Consolectl Ioctls
290 The user process issues console
291 .Fn ioctl
292 calls to the current virtual console in order to control
293 the mouse pointer.
294 The console
295 .Fn ioctl
296 also provides a method for the user process to receive a
297 .Xr signal 3
298 when a button is pressed.
299 .Pp
300 The mouse daemon
301 .Xr moused 8
302 uses
303 .Fn ioctl
304 calls to the console control device
305 .Pa /dev/consolectl
306 to inform the console of mouse actions including mouse movement
307 and button status.
308 .Pp
309 Both classes of
310 .Fn ioctl
311 commands are defined as
312 .Dv CONS_MOUSECTL
313 which takes the following argument.
314 .Bd -literal
315 struct mouse_info {
316 int operation;
317 union {
318 struct mouse_data data;
319 struct mouse_mode mode;
320 struct mouse_event event;
321 } u;
322 };
323 .Ed
324 .Pp
325 .Bl -tag -width operation -compact
326 .It Dv operation
327 This can be one of
328 .Pp
329 .Bl -tag -width MOUSE_MOVEABS -compact
330 .It Dv MOUSE_SHOW
331 Enables and displays mouse cursor.
332 .It Dv MOUSE_HIDE
333 Disables and hides mouse cursor.
334 .It Dv MOUSE_MOVEABS
335 Moves mouse cursor to position supplied in
336 .Dv u.data .
337 .It Dv MOUSE_MOVEREL
338 Adds position supplied in
339 .Dv u.data
340 to current position.
341 .It Dv MOUSE_GETINFO
342 Returns current mouse position in the current virtual console
343 and button status in
344 .Dv u.data .
345 .It Dv MOUSE_MODE
346 This sets the
347 .Xr signal 3
348 to be delivered to the current process when a button is pressed.
349 The signal to be delivered is set in
350 .Dv u.mode .
351 .El
352 .Pp
353 The above operations are for virtual consoles.
354 The operations defined
355 below are for the console control device and are used by
356 .Xr moused 8
357 to pass mouse data to the console driver.
358 .Pp
359 .Bl -tag -width MOUSE_MOVEABS -compact
360 .It Dv MOUSE_ACTION
361 .It Dv MOUSE_MOTION_EVENT
362 These operations take the information in
363 .Dv u.data
364 and act upon it.
365 Mouse data will be sent to the
366 .Nm
367 driver if it is open.
368 .Dv MOUSE_ACTION
369 also processes button press actions and sends signal to the process if
370 requested or performs cut and paste operations
371 if the current console is a text interface.
372 .It Dv MOUSE_BUTTON_EVENT
373 .Dv u.data
374 specifies a button and its click count.
375 The console driver will
376 use this information for signal delivery if requested or
377 for cut and paste operations if the console is in text mode.
378 .El
379 .Pp
380 .Dv MOUSE_MOTION_EVENT
381 and
382 .Dv MOUSE_BUTTON_EVENT
383 are newer interface and are designed to be used together.
384 They are intended to replace functions performed by
385 .Dv MOUSE_ACTION
386 alone.
387 .Pp
388 .It Dv u
389 This union is one of
390 .Pp
391 .Bl -tag -width data -compact
392 .It Dv data
393 .Bd -literal
394 struct mouse_data {
395 int x;
396 int y;
397 int z;
398 int buttons;
399 };
400 .Ed
401 .Pp
402 .Dv x ,
403 .Dv y
404 and
405 .Dv z
406 represent movement of the mouse along respective directions.
407 .Dv buttons
408 tells the state of buttons.
409 It encodes up to 31 buttons in the bit 0 though
410 the bit 30.
411 If a button is held down, the corresponding bit is set.
412 .Pp
413 .It Dv mode
414 .Bd -literal
415 struct mouse_mode {
416 int mode;
417 int signal;
418 };
419 .Ed
420 .Pp
421 The
422 .Dv signal
423 field specifies the signal to be delivered to the process.
424 It must be
425 one of the values defined in
426 .In signal.h .
427 The
428 .Dv mode
429 field is currently unused.
430 .Pp
431 .It Dv event
432 .Bd -literal
433 struct mouse_event {
434 int id;
435 int value;
436 };
437 .Ed
438 .Pp
439 The
440 .Dv id
441 field specifies a button number as in
442 .Dv u.data.buttons .
443 Only one bit/button is set.
444 The
445 .Dv value
446 field
447 holds the click count: the number of times the user has clicked the button
448 successively.
449 .Pp
450 .El
451 .El
452 .Sh FILES
453 .Bl -tag -width /dev/consolectl -compact
454 .It Pa /dev/consolectl
455 device to control the console
456 .It Pa /dev/sysmouse
457 virtualized mouse driver
458 .It Pa /dev/ttyv%d
459 virtual consoles
460 .El
461 .Sh SEE ALSO
462 .Xr vidcontrol 1 ,
463 .Xr ioctl 2 ,
464 .Xr signal 3 ,
465 .Xr mouse 4 ,
466 .Xr moused 8
467 .Sh HISTORY
468 The
469 .Nm
470 manual page example first appeared in
471 .Fx 2.2 .
472 .Sh AUTHORS
473 .An -nosplit
474 This
475 manual page was written by
476 .An John-Mark Gurney Aq gurney_j@efn.org
477 and
478 .An Kazutaka Yokota Aq yokota@FreeBSD.org .