WSMOUSE(4) | Device Drivers Manual | WSMOUSE(4)

# NAME

`wsmouse` — generic mouse support in wscons

# SYNOPSIS

`wsmouse* at ...`

# DESCRIPTION

The `wsmouse` driver is an abstraction layer for mice and other pointing devices within the wscons(4) framework. It is attached to the hardware specific drivers and provides a character device interface which returns struct wscons_event via read(2). For use with X servers, “mouse events” or “touch events” can be generated.

The `wsmouse` driver provides a number of ioctl functions to control various parameters (see /usr/include/dev/wscons/wsconsio.h). The wsconsctl(8) utility gives access to these variables.

Touchpad input is processed in one of two modes: In “absolute mode”, the `wsmouse` driver generates touch events. Absolute mode is activated by synaptics(4). In “compatibility mode”, which is the default, `wsmouse` converts the input internally and generates mouse events. wsconsctl(8) can query and set several configuration parameters for this mode. The composite field names have the form `mouse`[N].`tp`.field where N is the index of the `wsmouse` device. If N is omitted, commands apply to /dev/wsmouse0.

`mouse.reverse_scrolling`
  Reverse direction of scrolling.
`mouse.scaling`
  The value is a scale coefficient that is applied to the relative coordinates. It determines the base speed of the pointer.
`mouse.tp.tapping`
  Contacts on the touchpad that are immediately released again can be mapped to mouse button clicks. This list of three parameters configures these mappings, in the order:

      one-finger,two-finger,three-finger

  Setting a parameter to a positive value enables that tap gesture and maps it to the given mouse button. To disable all three tap gestures at once, provide the single value of 0. Conversely, a single non-zero value will enable one-finger, two-finger, and three-finger tap gestures with their default mappings of left button, right button, and middle button, respectively. If, within a short time interval, a second touch follows a tap gesture mapped to a left-button click, the button-up event is not issued until that touch ends (“tap-and-drag”).

`mouse.tp.mtbuttons`
  This feature is supported for some clickpads. If enabled, two-finger clicks - with the fingers side by side - generate left-button events, and three-finger clicks generate middle-button events.
`mouse.tp.swapsides`
  If this parameter has a non-zero value, the order of software button areas is inverted. If edge scrolling is enabled, the scroll area is set up at the left edge of the touchpad.
`mouse.tp.disable`
  A non-zero value disables pointer movement, tapping, and scrolling. Software buttons (and external physical buttons) will work as usual.
`mouse.tp.edges`
  This field contains a list of four values that define the relative sizes of the edge areas, in the order:

      top,right,bottom,left

  The unit is percent of the total height of the touchpad surface, or of its total width, respectively. In order to mitigate the effects of accidental touches, the driver ignores most types of input from an edge area (see below). If an edge area contains software buttons, they fill up the space provided.

The automatic configuration enables two-finger scrolling and sets up edge areas at the vertical edges. On clickpads - where the device surface serves as a single, large button - it provides three software button areas at the bottom edge, for left-button, middle-button, and right-button clicks. On some laptops with a trackpoint, the software buttons are at the top edge. Vertical edge scrolling will be enabled on older touchpads that do not report contact counts.

A touch that starts and remains in an edge area does not trigger pointer movement. At the vertical edges and the top edge, tapping and two-finger scrolling require that at least one touch is in the main area of the touchpad (the exact behaviour of a single-touch device depends on its firmware in this case). When multi-touch input is available, a touch is ignored if it rests in the bottom area while there are other inputs - movement, scrolling, or tapping -, and the driver continues to ignore it as long as and whenever other touches are present.

## Ioctls

The following ioctl(2) calls are provided by the `wsmouse` driver or by devices which use it. Their definitions are found in dev/wscons/wsconsio.h.

`WSKBDIO_GTYPE`
  Get the mouse or device type.
`WSMOUSEIO_SRES` (int)
  Set the resolution of the pointer. Not applicable to all mouse types.
`WSMOUSEIO_GCALIBCOORDS, WSMOUSEIO_SCALIBCOORDS` (struct wsmouse_calibcoords)
  Get and set device calibration data for touchscreens.
`WSMOUSEIO_SETMODE` (int)
  Sets the mode of a touchpad device (`WSMOUSE_COMPAT` or `WSMOUSE_NATIVE`)
`WSMOUSEIO_GETPARAMS, WSMOUSEIO_SETPARAMS` (struct wsmouse_parameters)
  Obtain and set various mouse parameters as a key/value set. Currently these primarily relate to touchpads. The structure struct wsmouse_parameters is defined as follows:

      struct wsmouse_param {
      	enum wsmousecfg key;
      	int value;
      };

      struct wsmouse_parameters {
      	struct wsmouse_param *params;
      	unsigned int nparams;
      };

  The number of parameters to read or write must be specified in nparams. For each parameter, when `WSMOUSEIO_GETPARAMS` is used, a key must be specified. When `WSMOUSEIO_SETPARAMS` is used, a key and a value must be specified. A single ioctl may retrieve up to `WSMOUSECFG_MAX` nparams.

# FILES

/dev/wsmouse*
/usr/include/dev/wscons/wsconsio.h

# SEE ALSO

ams(4), hilms(4), intro(4), lms(4), mms(4), pms(4), ubcmtp(4), ums(4), utpms(4), wscons(4), wsmux(4), wsconsctl(8), wsmoused(8)

August 16, 2025 | Debian