Re: [PATCH v0 5/5] Add Documentation for console mouse reporting

[Randy Dunlap]

On 6/26/20 12:23 AM, Tammo Block wrote:
> 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@xxxxxxxxx>
> ---
>  .../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

preferable:
                react to

> +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

                                    ^^^^^^^^^^^^^^^^^^^^^^^
I don't understand what that means.

> +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,

               sent (as Jiri said)

> +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

                          sent

> +
> +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

                                                  sent

> +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/
> +
> +


-- 
~Randy