PSM(4)

💖 PSM(4) — the PS/2 mouse driver, explained by your favorite Unix bestie 💖

okay so this is the manual page for psm, from the Kernel Interfaces Manual section. it's giving "your mouse, but make it a whole kernel driver" and honestly? iconic. buckle up bestie, there's a LOT here 🐭✨

---

✨ NAME ✨

psm — the PS/2 mouse style pointing device driver 🖱️💅

---

✨ SYNOPSIS ✨

options KBD_RESETDELAY=N
options KBD_MAXWAIT=N
options PSM_DEBUG=N
options KBDIO_DEBUG=N
device psm

and then, in /boot/device.hints:

hint.psm.0.at="atkbdc"
hint.psm.0.irq="12"

---

✨ DESCRIPTION ✨

so the psm driver is what gives you support for the PS/2 mouse style pointing device. and listen — right now, there can only be one psm device node in the whole system. one mouse, one node, main character energy only 🎀

here's the tea though: the PS/2 mouse port literally lives at the auxiliary port of the keyboard controller. so the keyboard controller driver, atkbdc, has to be configured in the kernel too, or this whole thing falls apart. also ngl, there's currently no provision for changing the irq number. it is what it is.

a basic PS/2 style pointing device has two or three buttons. some devices are extra and come with a roller or a wheel and/or additional buttons. we love an overachiever 💅

---

🌀 Device Resolution

the PS/2 style pointing device usually has several grades of resolution — that's the sensitivity of movement, bestie. typically it's 25, 50, 100 and 200 pulse per inch. some devices get even finer than that, show-offs.

the current resolution can be changed at runtime, so you're not stuck with whatever it woke up with. the psm driver lets you initially set the resolution via the driver flag (peep “DRIVER CONFIGURATION”) or change it later via the ioctl(2) command MOUSE_SETMODE (peep “IOCTLS”). either way, you're in control ✨

---

🌀 Report Rate

frequency — or report rate — is how often the device sends movement and button state reports to the host system. also configurable, because of course it is.

the PS/2 style pointing device typically supports 10, 20, 40, 60, 80, 100 and 200 reports per second. and like, 60 or 100 appears to be the default value for a lot of devices. noted 📝

heads up: when there's no movement and no button has changed its state, the device will not send anything to the host system. it's not ghosting you, it's just being efficient. the report rate can be changed via an ioctl call.

---

🌀 Operation Levels

the psm driver has three levels of operation, and you can set the current one via an ioctl call. let's break it down 🧚

level zero is the basics era. the device driver reports horizontal and vertical movement of the attached device, plus the state of up to three buttons. the movement and status get encoded in a series of fixed-length data packets (peep “Data Packet Format”). this is the default level of operation, and the driver is initially at this level when opened by the user program.

level one, aka the extended level, supports a roller (or wheel) if there is one, plus up to 11 buttons. roller movement gets reported as movement along the Z axis. and at this level, 8 byte data packets are sent to the user program. no cap.

level two is the "raw and unfiltered" era. data from the pointing device is passed to the user program as is, and conversely, commands from the user program are passed to the pointing device as is. the user program is responsible for status validation and error recovery, so like... you better know what you're doing. modern PS/2 type pointing devices often use proprietary data formats, so at this level the user program is expected to have intimate knowledge of the format from that particular device. this level is called the native level. iykyk 👑

---

🌀 Data Packet Format

data packets read from the psm driver are formatted differently at each operation level. let's get into the lore.

at operation level zero, a data packet from the PS/2 mouse style pointing device is three bytes long:

Byte 1

• bit 7 — one indicates overflow in the vertical movement count.
• bit 6 — one indicates overflow in the horizontal movement count.
• bit 5 — set if the vertical movement count is negative.
• bit 4 — set if the horizontal movement count is negative.
• bit 3 — always one.
• bit 2 — middle button status; set if pressed. for devices without the middle button, this bit is always zero.
• bit 1 — right button status; set if pressed.
• bit 0 — left button status; set if pressed.

Byte 2 — horizontal movement count in two's complement; -256 through 255. note that the sign bit is in the first byte.

Byte 3 — vertical movement count in two's complement; -256 through 255. note that the sign bit is in the first byte.

at level one, a data packet is encoded in the standard format MOUSE_PROTO_SYSMOUSE as defined in mouse(4).

at level two — native level — there is no standard on the size and format of the data packet. it's the wild west out there 🤠

---

🌀 Acceleration

the psm driver can somewhat accelerate the movement of the pointing device. the faster you move the device, the further the pointer travels on the screen. physics? never heard of her 💫

the driver has an internal variable that governs the effect of the acceleration, and its value can be modified via the driver flag or via an ioctl call.

---

✨ DRIVER CONFIGURATION ✨

🌸 Kernel Configuration Options

there are the following kernel configuration options to control the psm driver. they may be set in the kernel configuration file (peep config(8)).

• KBD_RESETDELAY=X, KBD_MAXWAIT=Y — the psm driver will attempt to reset the pointing device during the boot process. it sometimes takes a long while before the device will respond after reset. these options control how long the driver should wait before it eventually gives up waiting. the driver will wait X * Y msecs at most. if the driver seems unable to detect your pointing device, you may want to increase these values. the default values are 200 msec for X and 5 for Y.
• PSM_DEBUG=N, KBDIO_DEBUG=N — sets the debug level to N. the default debug level is zero. peep “DIAGNOSTICS” for debug logging.

---

🌸 Driver Flags

the psm driver accepts the following driver flags. set them in /boot/device.hints (peep “EXAMPLES” below).

• bit 0..3 RESOLUTION — this flag specifies the resolution of the pointing device. it must be zero through four. the greater the value is, the finer the resolution the device will select. the actual resolution selected by this field varies according to the model of the device. typical resolutions are:
  • 1 (low) — 25 pulse per inch (ppi)
  • 2 (medium low) — 50 ppi
  • 3 (medium high) — 100 ppi
  • 4 (high) — 200 ppi

leaving this flag zero will select the default resolution for the device (whatever it is).

• bit 4..7 ACCELERATION — this flag controls the amount of acceleration effect. the smaller the value of this flag is, the 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 disable the acceleration effect.
• bit 8 NOCHECKSYNC — the psm driver tries to detect the first byte of the data packet by checking the bit pattern of that byte. although this method should work with most PS/2 pointing devices, it may interfere with some devices which are not so compatible with known devices. if you think your pointing device is not functioning as expected, and the kernel frequently prints the following message to the console,

psmintr: out of sync (xxxx != yyyy).

set this flag to disable synchronization check and see if it helps.

• bit 9 NOIDPROBE — the psm driver will not try to identify the model of the pointing device and will not carry out model-specific initialization. the device should always act like a standard PS/2 mouse without such initialization. extra features, such as wheels and additional buttons, will not be recognized by the psm driver. so like, you get a mouse, but a basic one. respect the simplicity 💜
• bit 10 NORESET — when this flag is set, the psm driver will not reset the pointing device when initializing the device. if the FreeBSD kernel is started after another OS has run, the pointing device will inherit settings from the previous OS. however, because there is no way for the psm driver to know the settings, the device and the driver may not work correctly. the flag should never be necessary under normal circumstances. fr fr.
• bit 11 FORCETAP — some pad devices report as if the fourth button is pressed when the user taps the surface of the device (peep “CAVEATS”). this flag will make the psm driver assume that the device behaves this way. without the flag, the driver will assume this behavior for ALPS GlidePoint models only.
• bit 12 IGNOREPORTERROR — this flag makes the psm driver ignore certain error conditions when probing the PS/2 mouse port. it should never be necessary under normal circumstances.
• bit 13 HOOKRESUME — the built-in PS/2 pointing device of some laptop computers is somehow not operable immediately after the system resumes from the power saving mode, though it will eventually become available. there are reports that stimulating the device by performing I/O will help waking up the device quickly. this flag will enable a piece of code in the psm driver to hook the resume event and exercise some harmless I/O operations on the device. waking up your mouse with a lil tap, we love to see it ☀️
• bit 14 INITAFTERSUSPEND — this flag adds more drastic action for the above problem. it will cause the psm driver to reset and re-initialize the pointing device after the resume event. it's giving "we tried being gentle, now we're doing the full routine" 💀

---

✨ LOADER TUNABLES ✨

extended support for Synaptics touchpads can be enabled by setting hw.psm.synaptics_support to 1 at boot-time. this will enable psm to handle packets from guest devices (sticks) and extra buttons. similarly, extended support for IBM/Lenovo TrackPoint and Elantech touchpads can be enabled by setting hw.psm.trackpoint_support or hw.psm.elantech_support, respectively, to 1 at boot-time. look at all those tunables, slay 🎀

tap and drag gestures can be disabled by setting hw.psm.tap_enabled to 0 at boot-time. currently, this is supported on Synaptics touchpads regardless of Extended support state and on Elantech touchpads with Extended support enabled. the behaviour may be changed after boot by setting the sysctl with the same name and by restarting moused(8) using /etc/rc.d/moused.

active multiplexing support can be disabled by setting hw.psm.mux_disabled to 1 at boot-time. this will prevent psm from enabling active multiplexing mode needed for some Synaptics touchpads.

lowkey important: those last two paragraphs are your whole "i want to change this later" cheat code — same name, just via sysctl, and then restart moused(8) through /etc/rc.d/moused. 🦋

✨ IOCTLS ✨

ok so bestie, there are a few ioctl(2) commands for mouse drivers and they are everything. These commands plus their related structs and constants live in <sys/mouse.h>. The general rundown of the commands is in mouse(4) — this section is the psm-specific tea 💅.

---

• MOUSE_GETLEVEL int *level
• MOUSE_SETLEVEL int *level

These two commands manipulate the operation level of the psm driver. Simple as that, no cap.

---

• MOUSE_GETHWINFO mousehw_t *hw

Returns the hardware information of the attached device in this structure, and I need you to look at it because it's giving ✨:

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;

The buttons field holds the number of buttons on the device. The psm driver currently can detect the 3 button mouse from Logitech and report accordingly. The 3 button mouse from the other manufacturer may or may not be reported correctly. However, it will not affect the operation of the driver. (so like, no stress 🫶)

The iftype is always MOUSE_IF_PS2. Always. Periodt.

The type tells the device type: MOUSE_MOUSE, MOUSE_TRACKBALL, MOUSE_STICK, MOUSE_PAD, or MOUSE_UNKNOWN. The user should not heavily rely on this field, as the driver may not always — in fact it is very rarely able to — identify the device type. It's giving mystery. 🙈

The model is always MOUSE_MODEL_GENERIC at the operation level 0. It may be MOUSE_MODEL_GENERIC or one of MOUSE_MODEL_XXX constants at higher operation levels. Again the psm driver may or may not set an appropriate value in this field.

The hwid is the ID value returned by the device. Known IDs include:

• 0 — Mouse (Microsoft, Logitech and many other manufacturers)
• 2 — Microsoft Ballpoint mouse
• 3 — Microsoft IntelliMouse

---

• MOUSE_SYN_GETHWINFO synapticshw_t *synhw

Retrieves extra information associated with Synaptics Touchpad. Only available when a supported device has been detected. (touchpad girlies, this one's for you 🎀)

typedef struct synapticshw {
    int infoMajor;      /* major hardware revision */
    int infoMinor;      /* minor hardware revision */
    int infoRot180;     /* touchpad is rotated */
    int infoPortrait;   /* touchpad is a portrait */
    int infoSensor;     /* sensor model */
    int infoHardware;   /* hardware model */
    int infoNewAbs;     /* supports the newabs format */
    int capPen;         /* can detect a pen */
    int infoSimplC;     /* supports simple commands */
    int infoGeometry;   /* touchpad dimensions */
    int capExtended;    /* supports extended packets */
    int capSleep;       /* can be suspended/resumed */
    int capFourButtons; /* has four buttons */
    int capMultiFinger; /* can detect multiple fingers */
    int capPalmDetect;  /* can detect a palm */
    int capPassthrough; /* can passthrough guest packets */
    int capMiddle;      /* has a physical middle button */
    int nExtendedButtons; /* has N additional buttons */
    int nExtendedQueries; /* supports N extended queries */
} synapticshw_t;

See the Synaptics TouchPad Interfacing Guide for more information about the fields in this structure. 👑

---

• MOUSE_GETMODE mousemode_t *mode

The command gets the current operation parameters of the mouse driver. Look at this absolute unit of a struct:

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;

The protocol is MOUSE_PROTO_PS2 at the operation level zero and two. MOUSE_PROTO_SYSMOUSE at the operation level one.

The rate is the status report rate (reports/sec) at which the device will send movement report to the host computer. Typical supported values are 10, 20, 40, 60, 80, 100 and 200. Some mice may accept other arbitrary values too. (overachievers 💅)

The resolution of the pointing device must be one of MOUSE_RES_XXX constants or a positive value. The greater the value is, the finer resolution the mouse will select. Actual resolution selected by the MOUSE_RES_XXX constant varies according to the model of mouse. Typical resolutions are:

• MOUSE_RES_LOW — 25 ppi
• MOUSE_RES_MEDIUMLOW — 50 ppi
• MOUSE_RES_MEDIUMHIGH — 100 ppi
• MOUSE_RES_HIGH — 200 ppi

The accelfactor field holds a value to control acceleration feature (see “Acceleration”). It must be zero or greater. If it is zero, acceleration is disabled.

The packetsize field specifies the length of the data packet. It depends on the operation level and the model of the pointing device.

• level 0 — 3 bytes
• level 1 — 8 bytes
• level 2 — Depends on the model of the device

The array syncmask holds a bit mask and pattern to detect the first byte of the data packet. syncmask[0] is the bit mask to be ANDed with a byte. If the result is equal to 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. (it's giving "trust me bro" energy but make it a bitmask 😭)

---

• MOUSE_SETMODE mousemode_t *mode

The command changes the current operation parameters of the mouse driver as specified in mode. Only rate, resolution, level and accelfactor may be modifiable. Setting values in the other field does not generate error and has no effect.

If you do not want to change the current setting of a field, put -1 there. You may also put zero in resolution and rate, and the default value for the fields will be selected.

---

• MOUSE_READDATA mousedata_t *data
• MOUSE_READSTATE mousedata_t *state

These commands are not currently supported by the psm driver. 💀 (sorry bestie, they simply said no)

---

• MOUSE_GETSTATUS mousestatus_t *status

The command returns the current state of buttons and movement counts as described in mouse(4).

---

📁 FILES 📁

• /dev/psm0 — `non-blocking' device node
• /dev/bpsm0 — `blocking' device node

---

🌸 EXAMPLES 🌸

In order to install the psm driver, you need to add

device atkbdc
device psm

to your kernel configuration file, and put the following lines to /boot/device.hints.

hint.atkbdc.0.at="isa"
hint.atkbdc.0.port="0x060"
hint.psm.0.at="atkbdc"
hint.psm.0.irq="12"

If you add the following statement to /boot/device.hints,

hint.psm.0.flags="0x2000"

you will add the optional code to stimulate the pointing device after the `resume' event.

hint.psm.0.flags="0x24"

The above line will set the device resolution high (4) and the acceleration factor to 2. slay 🔥

---

🩺 DIAGNOSTICS 🩺

At debug level 0, little information is logged except for the following line during boot process:

psm0: device ID X

where X the device ID code returned by the found pointing device. See MOUSE_GETINFO for known IDs.

At debug level 1 more information will be logged while the driver probes the auxiliary port (mouse port). Messages are logged with the LOG_KERN facility at the LOG_DEBUG level (see syslogd(8)).

psm0: current command byte:xxxx
kbdio: TEST_AUX_PORT status:0000
kbdio: RESET_AUX return code:00fa
kbdio: RESET_AUX status:00aa
kbdio: RESET_AUX ID:0000
[...]
psm: status 00 02 64
psm0 irq 12 on isa
psm0: model AAAA, device ID X, N buttons
psm0: config:00000www, flags:0000uuuu, packet size:M
psm0: syncmask:xx, syncbits:yy

The first line shows the command byte value of the keyboard controller just before the auxiliary port is probed. It usually is 40, 45, 47 or 65, depending on how the motherboard BIOS initialized the keyboard controller upon power-up.

The second line shows the result of the keyboard controller's test on the auxiliary port interface, with zero indicating no error; note that some controllers report no error even if the port does not exist in the system, however. (sneaky little liars 🫠)

The third through fifth lines show the reset status of the pointing device. The functioning device should return the sequence of FA AA <ID>. The ID code is described above.

The seventh line shows the current hardware settings. These bytes are formatted as follows:

Byte 1

• bit 7 — Reserved.
• bit 6 — 0 - stream mode, 1 - remote mode. In the stream mode, the pointing device sends the device status whenever its state changes. In the remote mode, the host computer must request the status to be sent. The psm driver puts the device in the stream mode.
• bit 5 — Set if the pointing device is currently enabled. Otherwise zero.
• bit 4 — 0 - 1:1 scaling, 1 - 2:1 scaling. 1:1 scaling is the default.
• bit 3 — Reserved.
• bit 2 — Left button status; set if pressed.
• bit 1 — Middle button status; set if pressed.
• bit 0 — Right button status; set if pressed.

Byte 2

• bit 7 — Reserved.
• bit 6..0 — Resolution code: zero through three. Actual resolution for the resolution code varies from one device to another.

Byte 3

The status report rate (reports/sec) at which the device will send movement report to the host computer.

Note that the pointing device will not be enabled until the psm driver is opened by the user program. (it's waiting for you, bestie 🥺)

The rest of the lines show the device ID code, the number of detected buttons and internal variables.

At debug level 2, much more detailed information is logged. ✨

---

👀 SEE ALSO 👀

ioctl(2), syslog(3), atkbdc(4), mouse(4), mse(4), sysmouse(4), moused(8), syslogd(8)

Synaptics TouchPad Interfacing Guide, http://www.synaptics.com/.

👑 AUTHORS

okay so the psm driver? not a solo project bestie, it's built on the work of quite a number of people 🫶. The lineup includes Eric Forsberg, Sandi Donno, Rick Macklem, Andrew Herbert, Charles Hannum, Shoji Yuen and Kazutaka Yokota — just to name the few, because apparently there were more and they're all legends 💖.

This manual page itself was written by Kazutaka Yokota <yokota@FreeBSD.org>. Periodt. Credit given where credit is due, no cap. ✨

---

💀 CAVEATS

okay bestie, here's the tea, and it's giving "read this before you file a bug" 🍓:

• Many pad devices will act like the first (left) button got pressed the moment the user taps the surface of the pad. That's just... the vibe of the hardware. 🙈
• But some pad products — like some versions of ALPS GlidePoint and Interlink VersaPad — treat that tapping action as fourth button events instead. Different firmware, different delulu. 💅

It's been reported that ALPS GlidePoint, Synaptics Touchpad, IBM/Lenovo TrackPoint, and Interlink VersaPad all need the INITAFTERSUSPEND flag to actually recover from suspended state 😭. Good news though: that flag gets automatically set when one of these devices is detected by the psm driver. So like, the driver knows. She's on it. 👑

Some PS/2 mouse models from MouseSystems lowkey require being put in high resolution mode to work properly. Use the driver flag to set resolution, bestie. Do not skip this step. ⭐

okay and here's the serious one: there is not a guaranteed way to re-synchronize with the first byte of the packet once you're out of synchronization with the data stream. That's just the rules. 😔

If you're using the XFree86 server and you're experiencing this problem, you may be able to make the X server synchronize with the mouse by switching away to a virtual terminal and then getting back to the X server — unless the X server is accessing the mouse via moused(8), in which case nope 🫠. Clicking any button without moving the mouse may also work. Try it, it's giving "have you tried turning it off and on again" but for trackpads. 🌈

---

🐛 BUGS

Enabling the extended support for Synaptics touchpads has been reported to cause problems with responsivity on some (newer) models of Synaptics hardware, particularly those with guest devices. 💀

So like... it works, but at what cost. It's giving main character energy with a little too much going on. 🔥

---

and that's the whole page bestie!! you read all of it, slay 💅✨

this one's from Debian, dated June 2, 2020, and it's page PSM(4) — go forth and configure ur trackpad, ily, bye 🎀🦋💜