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