/share/man/man4/man4.i386/mse.4
https://bitbucket.org/freebsd/freebsd-head/ · Forth · 385 lines · 385 code · 0 blank · 0 comment · 15 complexity · 1028bc87a1d80b78bdaa3bc0550c001e MD5 · raw file
- .\" Copyright 1992 by the University of Guelph
- .\"
- .\" Permission to use, copy and modify this
- .\" software and its documentation for any purpose and without
- .\" fee is hereby granted, provided that the above copyright
- .\" notice appear in all copies and that both that copyright
- .\" notice and this permission notice appear in supporting
- .\" documentation.
- .\" University of Guelph makes no representations about the suitability of
- .\" this software for any purpose. It is provided "as is"
- .\" without express or implied warranty.
- .\"
- .\" $FreeBSD$
- .\"
- .Dd December 3, 1997
- .Dt MSE 4 i386
- .Os
- .Sh NAME
- .Nm mse
- .Nd bus and InPort mice driver
- .Sh SYNOPSIS
- .\" .Cd "options MSE_XXX=N"
- .Cd "device mse"
- .Pp
- In
- .Pa /boot/device.hints :
- .Cd hint.mse.0.at="isa"
- .Cd hint.mse.0.port="0x23c"
- .Cd hint.mse.0.irq="5"
- .Sh DESCRIPTION
- The
- .Nm
- driver provides support for the bus mouse and the InPort mouse, which
- are often collectively called ``bus'' mice, as these mice are sold with
- an interface card which needs to be installed in an expansion bus slot.
- The interface circuit may come on an integrated I/O card or as an option
- on video cards.
- .Pp
- The bus and InPort mice have two or three buttons,
- and a D-sub 9-pin male connector or a round DIN 9-pin
- male connector.
- .Pp
- The primary port address of the bus and InPort mouse interface cards
- is usually 0x23c.
- Some cards may also be set to use the secondary port
- address at 0x238.
- The interface cards require a single IRQ, which may be
- 2, 3, 4 or 5.
- Some cards may offer additional IRQs.
- The port number and the IRQ number are configured by jumpers on the cards
- or by software provided with the card.
- .Pp
- Frequency, or report rate, at which the device sends movement
- and button state reports to the host system, may also be configurable on
- some interface cards.
- It may be 15, 30, 60 or 120Hz.
- .Pp
- The difference between the two types of the mice is not in mouse devices
- (in fact they are exactly the same).
- But in the circuit on the interface
- cards.
- This means that the device from a bus mouse package can be
- connected to the interface card from an InPort mouse package, or vice
- versa, provided that their connectors match.
- .Ss Operation Levels
- The
- .Nm
- driver has two levels of operation.
- The current operation level can be set via an ioctl call.
- .Pp
- At the level zero the basic support is provided; the device driver will report
- horizontal and vertical movement of the attached device
- and state of up to three buttons in the format described below.
- It is a subset of the MouseSystems protocol.
- .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
- Horizontal movement count in two's compliment; -128 through 127.
- .It Byte 3
- Vertical movement count in two's compliment; -128 through 127.
- .It Byte 4
- Always zero.
- .It Byte 5
- Always zero.
- .El
- .Pp
- This is the default level of operation and the driver is initially
- at this level when opened by the user program.
- .Pp
- At the operation level one (extended level), a data packet 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.
- .Ss Device Number
- The minor device number of the
- .Nm
- is made up of:
- .Bd -literal -offset indent
- minor = (`unit' << 1) | `non-blocking'
- .Ed
- .Pp
- where `unit' is the device number (usually 0) and the `non-blocking' bit
- is set to indicate ``do not block waiting for mouse input,
- return immediately''.
- The `non-blocking' bit should be set for \fIXFree86\fP,
- therefore the minor device number usually used for \fIXFree86\fP is 1.
- See
- .Sx FILES
- for device node names.
- .Sh DRIVER CONFIGURATION
- .\" .Ss Kernel Configuration Options
- .Ss Driver Flags
- The
- .Nm
- driver accepts the following driver flag.
- Set it in the
- kernel configuration file
- (see
- .Xr config 8 )
- or in the User Configuration Menu at
- the boot time
- (see
- .Xr boot 8 ) .
- .Bl -tag -width MOUSE
- .It bit 4..7 ACCELERATION
- This flag controls the amount of acceleration effect.
- The smaller the value of this flag is, more sensitive the movement becomes.
- The minimum value allowed, thus the value for the most sensitive setting,
- is one.
- Setting this flag to zero will completely disables the
- acceleration effect.
- .El
- .Sh IOCTLS
- There are a few
- .Xr ioctl 2
- commands for mouse drivers.
- These commands and related structures and constants are defined in
- .In sys/mouse.h .
- General description of the commands is given in
- .Xr mouse 4 .
- This section explains 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
- .Nm
- 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 by 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 on the device.
- .Pp
- The
- .Dv iftype
- is either
- .Dv MOUSE_IF_BUS
- or
- .Dv MOUSE_IF_INPORT .
- .Pp
- The
- .Dv type
- may be
- .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 0.
- .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), -1 if unknown */
- 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
- is either
- .Dv MOUSE_PROTO_BUS
- or
- .Dv MOUSE_PROTO_INPORT
- at the operation level zero.
- .Dv MOUSE_PROTO_SYSMOUSE
- at the operation level one.
- .Pp
- The
- .Dv rate
- is the status report rate (reports/sec) at which the device will send
- movement report to the host computer.
- As there is no standard to detect the current setting,
- this field is always set to -1.
- .Pp
- The
- .Dv resolution
- is always set to -1.
- .Pp
- The
- .Dv accelfactor
- field holds a value to control acceleration feature
- (see
- .Sx Acceleration ) .
- It is zero or greater.
- If it is zero, acceleration is disabled.
- .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 detection method is not 100% reliable,
- thus, should be taken only as an advisory measure.
- .Pp
- Only
- .Dv level
- and
- .Dv accelfactor
- are modifiable by the
- .Dv MOUSE_SETMODE
- command.
- Changing the other field does not cause error, but has no effect.
- .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
- and
- .Dv accelfactor
- 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 as described in
- .Xr mouse 4 .
- .El
- .Sh FILES
- .Bl -tag -width /dev/nmse0 -compact
- .It Pa /dev/mse0
- `non-blocking' device node in the system without
- .Em devfs ,
- `blocking' under
- .Em devfs .
- .It Pa /dev/nmse0
- `non-blocking' device node under
- .Em devfs .
- .El
- .Sh EXAMPLES
- .Dl "device mse"
- .Pp
- In
- .Pa /boot/device.hints :
- .Dl hint.mse.0.at="isa"
- .Dl hint.mse.0.port="0x23c"
- .Dl hint.mse.0.irq="5"
- .Pp
- Add the
- .Nm
- driver at the primary port address with the IRQ 5.
- .Pp
- .Dl "device mse"
- .Pp
- .Dl hint.mse.1.at="isa"
- .Dl hint.mse.1.port="0x238"
- .Dl hint.mse.1.irq="4"
- .Dl hint.mse.1.flags="0x30"
- .Pp
- Define the
- .Nm
- driver at the secondary port address with the IRQ 4 and the acceleration
- factor of 3.
- .Sh SEE ALSO
- .Xr ioctl 2 ,
- .Xr mouse 4 ,
- .Xr psm 4 ,
- .Xr sysmouse 4 ,
- .Xr moused 8
- .\".Sh HISTORY
- .Sh CAVEATS
- Some bus mouse interface cards generate interrupts at the fixed report rate
- when enabled, whether or not the mouse state is changing.
- The others generate interrupts only when the state is changing.