[lkml]   [2020]   [Jun]   [30]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
Messages in this thread
Patch in this message
Subject[PATCH v1 6/6] Documentation: Describe console mouse reporting
This patch adds a description of the kernel interface(s) used for vt
console mouse reporting and describes the protocols and bitmasks.

Signed-off-by: Tammo Block <>
.../admin-guide/console-mouse-reporting.rst | 92 +++++++++++++++++++
Documentation/admin-guide/index.rst | 1 +
2 files changed, 93 insertions(+)
create mode 100644 Documentation/admin-guide/console-mouse-reporting.rst

diff --git a/Documentation/admin-guide/console-mouse-reporting.rst b/Documentation/admin-guide/console-mouse-reporting.rst
new file mode 100644
index 000000000000..11287cb233ba
--- /dev/null
+++ b/Documentation/admin-guide/console-mouse-reporting.rst
@@ -0,0 +1,92 @@
+.. SPDX-License-Identifier: GPL-2.0
+Console Mouse Reporting
+A terminal may send escape sequences to enable applications to react to mouse
+input. As the kernel does not know when to emit these events a mouse daemon
+is needed to react to mouse movements and signal the kernel accordingly. The
+kernel will then send an escape sequence to the application. This is called
+mouse reporting and several types and protocols have been developed over time.
+See tiocl.h, the :manpage:`ioctl_console(2)` and :manpage:`console_codes(4)`
+man pages and the xterm [1]_ or terminalguide [2]_ home pages for a detailed
+list and description of the various protocols, their bit layout as well as
+their limitations.
+Events and formats
+A linux console keeps state about two different aspects of mouse reporting,
+the kind of **events** to be reported and the **format** to send to userspace.
+A mouse daemon can check which kind of mouse events a clients wants to be
+informed about via the TIOCLINUX ioctl, using the TIOCL_GETMOUSEREPORTING
+subcall. The values of the supported event classes (9, 1000, 1002, 1003) are
+described in tiocl.h. Based on this information the daemon is responsible
+for not sending data packages for unrequested events.
+A userspace client may request to be informed by the kernel about one of
+the event classes and chose one of the data formats URXVT (1005), SRG
+(1006) or X10/X11 (default) via console escape sequences. In general all
+of them encode similar information, only the escape sequences differ.
+See the xterm [1]_ or terminalguide [2]_ home pages for all details.
+Reports from kernel to userspace client
+The requested events are sent by the kernel to userspace encoded in a
+escape sequence, details depend on the chosen format. All of them use one
+based pointer coordinates and a single byte to encode the button status.
+Short summary (we call this the SRG button format for the rest of this text):
+ - 1,2 : Buttons, lower bits (see notes below)
+ - 3-5 : Modifier keys (Shift, Alt and Ctrl)
+ - 6 : Mouse movement only, no button status change
+ - 7-8 : Buttons, upper bits (for buttons 4-15)
+Reports send from daemon to kernel
+A report is send by a mouse daemon to the kernel via the TIOCLINUX ioctl,
+using the TIOCL_SETSEL subcall. The coordinates are encoded zero based in
+xs and ys, with 0,0 as upper left corner, but see note below.
+The format used by the userspace mouse daemon for button encoding is almost
+identical to the SRG button layout decribed above and is put into the sel_mode
+of the tiocl_selection struct. All bits masked in TIOCL_SELBUTTONMASK are
+unchanged compared to the SRG button format above, the remaining three are
+changed the following way :
+- 3,4 : Unused, must be zero. The kernel knows modifier key state anyway.
+- 5 : Always 1, identifies mouse report / TIOCL_SELMOUSEREPORT
+Button numbers are encoded like this:
+- 0-2 : Left, middle and right button
+- 3 : No button pressed / Button release
+- 4-15 : More buttons, e.g. 4 and 5 are scroll wheel
+Please note that button releases should only be reported for buttons 0-2.
+Also note that coordinates (xs,ys,xe,ye) are zero based for the TIOCL_SETSEL
+syscall but one based for the escape sequences sent by the kernel, so the
+kernel will increase all coordinates by one.
+Older kernels only used the lower 4 bits of sel_mode, effectively limiting
+the protocol to 3 buttons and button click only. The meaning of the 4 bits
+is equivalent to the SRG button layout. Note that newer kernel will ignore
+the upper two bits (modifier keys).
+.. [1]
+.. [2]
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 58c7f9fc2396..c535902f3851 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -71,6 +71,7 @@ configure specific aspects of kernel behavior to your liking.
+ console-mouse-reporting
 \ /
  Last update: 2020-06-30 09:12    [W:0.103 / U:4.604 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site