Messages in this thread Patch in this message | | | Date | Fri, 26 Jun 2020 09:23:18 +0200 | From | Tammo Block <> | Subject | [PATCH v0 5/5] Add Documentation for console mouse reporting |
| |
This patch adds a description of the kernel interface(s) used for mouse reporting and compares the old and new bitmask layout.
Signed-off-by: Tammo Block <tammo.block@gmail.com> --- .../admin-guide/console-mouse-reporting.rst | 82 +++++++++++++++++++ Documentation/admin-guide/index.rst | 1 + 2 files changed, 83 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..799288295655 --- /dev/null +++ b/Documentation/admin-guide/console-mouse-reporting.rst @@ -0,0 +1,82 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================= +Console Mouse Reporting +======================= + +A terminal may send escape sequences to enable applications to react on mouse +input. As the kernel does not know when to emit these events a mouse daemon +is needed to react on 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. + +You can check which mouse events are requested *clients* via the TIOCLINUX +ioctl, using the TIOCL_GETMOUSEREPORTING subcall. The values of these event +classes (9, 1000, 1002, 1003, 1005) are described in tiocl.h. + +Report layout +------------- + +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 bits of the sel_mode are used the following way: + +X10/X11 like protocol ++++++++++++++++++++++ + +For the X10/X11 like protocol (if DECSET 1005 is *not* set), the lower 5 bits +of the sel_mode are used like this: + +- 1,2 : Encode Buttons (see notes below) / TIOCL_SELBUTTONMASK +- 3,4 : Modifier keys (Shift, Alt) / TIOCL_SELBUTTONMASK +- 5 : Always 1, identifies X10 protocol / TIOCL_SELMOUSEREPORT + +SRG protocol +++++++++++++ + +For the SRG style protocol (xterm style, DECSET 1005 *is* set) the upper 11 +bits of sel_mode are used like this: + +- 6 : Always 1, identifies SRG protocol / TIOCL_SELSRGREPORT +- 7 : Unused, should be 0. Ignored by kernel (future extensions) +- 8 : Set on button release events / TIOCL_SELSRGRELEASE +- 9-16 : The SRG byte, send to userspace as is / TIOCL_SELSRGMASK + +The SRG (upper) byte +++++++++++++++++++++ + +The layout of the *upper byte* ("SRG") is identical to the SRG data layout, +for protocol "1005", as described in detail in the xterm [1]_ or +terminalguide [2]_ home pages. Short summary: + + - 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) + +Notes ++++++ + +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 send by the kernel, so the +kernel will increase all coordinates by one. + +.. [1] https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking +.. [2] https://terminalguide.namepad.de/mouse/ + + 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. cgroup-v2 cifs/index clearing-warn-once + console-mouse-reporting cpu-load cputopology dell_rbu -- 2.27.0
| |