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