Re: [PATCH v1 6/6] Documentation: Describe console mouse reporting
Hi-- (duplicating some of Juri's comments) On 6/30/20 12:12 AM, Tammo Block wrote: > 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 ..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, Linux > +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 client > +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 choose > +(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 an > +escape sequence, details depend on the chosen format. All of them use one sequence; details > +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 sent > +++ > + > +A report is send by a mouse daemon to the kernel via the TIOCLINUX ioctl, sent > +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 described > +of the tiocl_selection struct. All bits masked in TIOCL_SELBUTTONMASK are > +unchanged compared to the SRG button format above, the remaining three are above; the > +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 > + > +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 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
Re: [PATCH v1 6/6] Documentation: Describe console mouse reporting
Cc Randy who commented on v0 (you should have done it). On 30. 06. 20, 9:12, Tammo Block wrote: > 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 ..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 client > +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 an > +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 sent > +++ > + > +A report is send by a mouse daemon to the kernel via the TIOCLINUX ioctl, sent (Randy pointed out this one already) > +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. I think "the" is missing twice in that sentence, but leave it as is unless some native speaker confirms. > +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 described > +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 : no space belongs before colons, here in Europe. > + > +- 3,4 : Unused, must be zero. The kernel knows modifier key state anyway. > +- 5: Always 1, identifies mouse report / TIOCL_SELMOUSEREPORT > + > +Notes > ++ ... thanks, -- js suse labs
[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 ..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 + +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 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] 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
