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