| blob | 7f83dcc87a97bb74d6c5cc5f02af4fe54ec7d7e5 |
1 .\" Copyright 1992 by the University of Guelph
2 .\"
3 .\" Permission to use, copy and modify this
4 .\" software and its documentation for any purpose and without
5 .\" fee is hereby granted, provided that the above copyright
6 .\" notice appear in all copies and that both that copyright
7 .\" notice and this permission notice appear in supporting
8 .\" documentation.
9 .\" University of Guelph makes no representations about the suitability of
10 .\" this software for any purpose. It is provided "as is"
11 .\" without express or implied warranty.
12 .\"
13 .\" $FreeBSD$
14 .\"
15 .Dd December 3, 1997
16 .Dt MSE 4 i386
17 .Os
18 .Sh NAME
19 .Nm mse
20 .Nd bus and InPort mice driver
21 .Sh SYNOPSIS
22 .\" .Cd "options MSE_XXX=N"
23 .Cd "device mse"
24 .Pp
25 In
26 .Pa /boot/device.hints :
27 .Cd hint.mse.0.at="isa"
28 .Cd hint.mse.0.port="0x23c"
29 .Cd hint.mse.0.irq="5"
30 .Sh DESCRIPTION
31 The
32 .Nm
33 driver provides support for the bus mouse and the InPort mouse, which
34 are often collectively called ``bus'' mice, as these mice are sold with
35 an interface card which needs to be installed in an expansion bus slot.
36 The interface circuit may come on an integrated I/O card or as an option
37 on video cards.
38 .Pp
39 The bus and InPort mice have two or three buttons,
40 and a D-sub 9-pin male connector or a round DIN 9-pin
41 male connector.
42 .Pp
43 The primary port address of the bus and InPort mouse interface cards
44 is usually 0x23c.
45 Some cards may also be set to use the secondary port
46 address at 0x238.
47 The interface cards require a single IRQ, which may be
48 2, 3, 4 or 5.
49 Some cards may offer additional IRQs.
50 The port number and the IRQ number are configured by jumpers on the cards
51 or by software provided with the card.
52 .Pp
53 Frequency, or report rate, at which the device sends movement
54 and button state reports to the host system, may also be configurable on
55 some interface cards.
56 It may be 15, 30, 60 or 120Hz.
57 .Pp
58 The difference between the two types of the mice is not in mouse devices
59 (in fact they are exactly the same).
60 But in the circuit on the interface
61 cards.
62 This means that the device from a bus mouse package can be
63 connected to the interface card from an InPort mouse package, or vice
64 versa, provided that their connectors match.
65 .Ss Operation Levels
66 The
67 .Nm
68 driver has two levels of operation.
69 The current operation level can be set via an ioctl call.
70 .Pp
71 At the level zero the basic support is provided; the device driver will report
72 horizontal and vertical movement of the attached device
73 and state of up to three buttons in the format described below.
74 It is a subset of the MouseSystems protocol.
75 .Pp
76 .Bl -tag -width Byte_1 -compact
77 .It Byte 1
78 .Bl -tag -width bit_7 -compact
79 .It bit 7
80 Always one.
81 .It bit 6..3
82 Always zero.
83 .It bit 2
84 Left button status; cleared if pressed, otherwise set.
85 .It bit 1
86 Middle button status; cleared if pressed, otherwise set.
87 Always one,
88 if the device does not have the middle button.
89 .It bit 0
90 Right button status; cleared if pressed, otherwise set.
91 .El
92 .It Byte 2
93 Horizontal movement count in two's compliment; -128 through 127.
94 .It Byte 3
95 Vertical movement count in two's compliment; -128 through 127.
96 .It Byte 4
97 Always zero.
98 .It Byte 5
99 Always zero.
100 .El
101 .Pp
102 This is the default level of operation and the driver is initially
103 at this level when opened by the user program.
104 .Pp
105 At the operation level one (extended level), a data packet is encoded
106 in the standard format
107 .Dv MOUSE_PROTO_SYSMOUSE
108 as defined in
109 .Xr mouse 4 .
110 .Ss Acceleration
111 The
112 .Nm
113 driver can somewhat `accelerate' the movement of the pointing device.
114 The faster you move the device, the further the pointer
115 travels on the screen.
116 The driver has an internal variable which governs the effect of
117 the acceleration.
118 Its value can be modified via the driver flag
119 or via an ioctl call.
120 .Ss Device Number
121 The minor device number of the
122 .Nm
123 is made up of:
124 .Bd -literal -offset indent
125 minor = (`unit' << 1) | `non-blocking'
126 .Ed
127 .Pp
128 where `unit' is the device number (usually 0) and the `non-blocking' bit
129 is set to indicate ``do not block waiting for mouse input,
130 return immediately''.
131 The `non-blocking' bit should be set for \fIXFree86\fP,
132 therefore the minor device number usually used for \fIXFree86\fP is 1.
133 See
134 .Sx FILES
135 for device node names.
136 .Sh DRIVER CONFIGURATION
137 .\" .Ss Kernel Configuration Options
138 .Ss Driver Flags
139 The
140 .Nm
141 driver accepts the following driver flag.
142 Set it in the
143 kernel configuration file
144 (see
145 .Xr config 8 )
146 or in the User Configuration Menu at
147 the boot time
148 (see
149 .Xr boot 8 ) .
150 .Pp
151 .Bl -tag -width MOUSE
152 .It bit 4..7 ACCELERATION
153 This flag controls the amount of acceleration effect.
154 The smaller the value of this flag is, more sensitive the movement becomes.
155 The minimum value allowed, thus the value for the most sensitive setting,
156 is one.
157 Setting this flag to zero will completely disables the
158 acceleration effect.
159 .El
160 .Sh IOCTLS
161 There are a few
162 .Xr ioctl 2
163 commands for mouse drivers.
164 These commands and related structures and constants are defined in
165 .In sys/mouse.h .
166 General description of the commands is given in
167 .Xr mouse 4 .
168 This section explains the features specific to the
169 .Nm
170 driver.
171 .Pp
172 .Bl -tag -width MOUSE -compact
173 .It Dv MOUSE_GETLEVEL Ar int *level
174 .It Dv MOUSE_SETLEVEL Ar int *level
175 These commands manipulate the operation level of the
176 .Nm
177 driver.
178 .Pp
179 .It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
180 Returns the hardware information of the attached device in the following
181 structure.
182 Only the
183 .Dv iftype
184 field is guaranteed to be filled with the correct value by the current
185 version of the
186 .Nm
187 driver.
188 .Bd -literal
189 typedef struct mousehw {
190 int buttons; /* number of buttons */
191 int iftype; /* I/F type */
192 int type; /* mouse/track ball/pad... */
193 int model; /* I/F dependent model ID */
194 int hwid; /* I/F dependent hardware ID */
195 } mousehw_t;
196 .Ed
197 .Pp
198 The
199 .Dv buttons
200 field holds the number of buttons on the device.
201 .Pp
202 The
203 .Dv iftype
204 is either
205 .Dv MOUSE_IF_BUS
206 or
207 .Dv MOUSE_IF_INPORT .
208 .Pp
209 The
210 .Dv type
211 may be
212 .Dv MOUSE_MOUSE ,
213 .Dv MOUSE_TRACKBALL ,
214 .Dv MOUSE_STICK ,
215 .Dv MOUSE_PAD ,
216 or
217 .Dv MOUSE_UNKNOWN .
218 .Pp
219 The
220 .Dv model
221 is always
222 .Dv MOUSE_MODEL_GENERIC
223 at the operation level 0.
224 It may be
225 .Dv MOUSE_MODEL_GENERIC
226 or one of
227 .Dv MOUSE_MODEL_XXX
228 constants at higher operation levels.
229 .Pp
230 The
231 .Dv hwid
232 is always 0.
233 .Pp
234 .It Dv MOUSE_GETMODE Ar mousemode_t *mode
235 The command gets the current operation parameters of the mouse
236 driver.
237 .Bd -literal
238 typedef struct mousemode {
239 int protocol; /* MOUSE_PROTO_XXX */
240 int rate; /* report rate (per sec), -1 if unknown */
241 int resolution; /* MOUSE_RES_XXX, -1 if unknown */
242 int accelfactor; /* acceleration factor */
243 int level; /* driver operation level */
244 int packetsize; /* the length of the data packet */
245 unsigned char syncmask[2]; /* sync. bits */
246 } mousemode_t;
247 .Ed
248 .Pp
249 The
250 .Dv protocol
251 is either
252 .Dv MOUSE_PROTO_BUS
253 or
254 .Dv MOUSE_PROTO_INPORT
255 at the operation level zero.
256 .Dv MOUSE_PROTO_SYSMOUSE
257 at the operation level one.
258 .Pp
259 The
260 .Dv rate
261 is the status report rate (reports/sec) at which the device will send
262 movement report to the host computer.
263 As there is no standard to detect the current setting,
264 this field is always set to -1.
265 .Pp
266 The
267 .Dv resolution
268 is always set to -1.
269 .Pp
270 The
271 .Dv accelfactor
272 field holds a value to control acceleration feature
273 (see
274 .Sx Acceleration ) .
275 It is zero or greater.
276 If it is zero, acceleration is disabled.
277 .Pp
278 The
279 .Dv packetsize
280 field specifies the length of the data packet.
281 It depends on the
282 operation level.
283 .Pp
284 .Bl -tag -width level_0__ -compact
285 .It Em level 0
286 5 bytes
287 .It Em level 1
288 8 bytes
289 .El
290 .Pp
291 The array
292 .Dv syncmask
293 holds a bit mask and pattern to detect the first byte of the
294 data packet.
295 .Dv syncmask[0]
296 is the bit mask to be ANDed with a byte.
297 If the result is equal to
298 .Dv syncmask[1] ,
299 the byte is likely to be the first byte of the data packet.
300 Note that this detection method is not 100% reliable,
301 thus, should be taken only as an advisory measure.
302 .Pp
303 Only
304 .Dv level
305 and
306 .Dv accelfactor
307 are modifiable by the
308 .Dv MOUSE_SETMODE
309 command.
310 Changing the other field does not cause error, but has no effect.
311 .Pp
312 .It Dv MOUSE_SETMODE Ar mousemode_t *mode
313 The command changes the current operation parameters of the mouse driver
314 as specified in
315 .Ar mode .
316 Only
317 .Dv level
318 and
319 .Dv accelfactor
320 may be modifiable.
321 Setting values in the other field does not generate
322 error and has no effect.
323 .\" .Pp
324 .\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
325 .\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
326 .\" These commands are not supported by the
327 .\" .Nm
328 .\" driver.
329 .Pp
330 .It Dv MOUSE_READDATA Ar mousedata_t *data
331 .It Dv MOUSE_READSTATE Ar mousedata_t *state
332 These commands are not supported by the
333 .Nm
334 driver.
335 .Pp
336 .It Dv MOUSE_GETSTATUS Ar mousestatus_t *status
337 The command returns the current state of buttons and
338 movement counts as described in
339 .Xr mouse 4 .
340 .El
341 .Sh FILES
342 .Bl -tag -width /dev/nmse0 -compact
343 .It Pa /dev/mse0
344 `non-blocking' device node in the system without
345 .Em devfs ,
346 `blocking' under
347 .Em devfs .
348 .It Pa /dev/nmse0
349 `non-blocking' device node under
350 .Em devfs .
351 .El
352 .Sh EXAMPLES
353 .Dl "device mse"
354 .Pp
355 In
356 .Pa /boot/device.hints :
357 .Dl hint.mse.0.at="isa"
358 .Dl hint.mse.0.port="0x23c"
359 .Dl hint.mse.0.irq="5"
360 .Pp
361 Add the
362 .Nm
363 driver at the primary port address with the IRQ 5.
364 .Pp
365 .Dl "device mse"
366 .Pp
367 .Dl hint.mse.1.at="isa"
368 .Dl hint.mse.1.port="0x238"
369 .Dl hint.mse.1.irq="4"
370 .Dl hint.mse.1.flags="0x30"
371 .Pp
372 Define the
373 .Nm
374 driver at the secondary port address with the IRQ 4 and the acceleration
375 factor of 3.
376 .Sh CAVEATS
377 Some bus mouse interface cards generate interrupts at the fixed report rate
378 when enabled, whether or not the mouse state is changing.
379 The others generate interrupts only when the state is changing.
380 .Sh SEE ALSO
381 .Xr ioctl 2 ,
382 .Xr mouse 4 ,
383 .Xr psm 4 ,
384 .Xr sysmouse 4 ,
385 .Xr moused 8
386 .\".Sh HISTORY