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