Skip to contentSkip to conversation

vt: Add SRG mouse reporting features

PATCH Superseded Tammo Block 3 participants 11 messages Jun 30, 2020

Subsystems (3)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

cover vt: Add SRG mouse reporting features

Hi everybody,

this patchset adds xterm like mouse reporting features to the console.

The linux virtual console has support for mouse reporting since 1994 or so, but the kernel only supports the original X10/X11 style standard protocols. To support more protocols these patches expand the kernel structures in a up- and downwards compatible way, see the last patch for detailed documentation and pointers to even more detailed docs.

The main goal is to become compatible with xterm, as most TUI software today is tested in xterm or another compatible terminal.

Support by the mouse daemons (consolation, gpm) will be needed too.

Kind regards,
Tammo

Changes from v0 :
- Fixed al the style the things mentioned by Jiri and Randy (thanks!)
- Change datastructure for report (better compatibility)
- Changed documentation in large parts accordingly
- Added URXVT protocol

Tammo Block (6):
tiocl.h: Change/Add defines for mouse report
console_struct.h: Two members for mouse report
vt/vt: Enable mode change via escape sequence
vt/vt: Add SRG mouse reporting protocol
vt/vt: Add URXVT mouse reporting protocol
Documentation: Describe console mouse reporting

 .../admin-guide/console-mouse-reporting.rst   | 92 +++++++++++++++++++
 Documentation/admin-guide/index.rst           |  1 +
 drivers/tty/vt/vt.c                           | 38 +++++++-
 include/linux/console_struct.h                |  3 +-
 include/uapi/linux/tiocl.h                    |  8 +-
 5 files changed, 134 insertions(+), 8 deletions(-)
 create mode 100644 Documentation/admin-guide/console-mouse-reporting.rst
Signature · 1 line
2.27.0
#1 lore raw

PATCH 1/6 tiocl.h: Change/Add defines for mouse report

Add additional defines for mouse event types. The change of the value of TIOCL_SELBUTTONMASK deserves a bit more explanation :

The old value of 15 uses the first 4 bits and sends them unchanged back to userspace if requested by an application. But in fact only the first two bits have ever been used by any daemon or useful at all, as the kernel already knows the status of the shift and alt keys encoded in bits 3 and 4. On the other hand we *do* want to know the status of bits 6-8, encoding button values >3 and mouse move and drag operations.

This change is up- and downwards compatible by masking all spourious bits and leaving only the undisputed parts (bits 1 and 2) untouched.

---
 include/uapi/linux/tiocl.h | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
include/uapi/linux/tiocl.h +6 -2
index b32acc229024..c862053041e4 100644
@@ -9,7 +9,7 @@
 #define 	TIOCL_SELPOINTER	3	/* show the pointer */
 #define 	TIOCL_SELCLEAR	4	/* clear visibility of selection */
 #define 	TIOCL_SELMOUSEREPORT	16	/* report beginning of selection */
-#define 	TIOCL_SELBUTTONMASK	15	/* button mask for report */
+#define 	TIOCL_SELBUTTONMASK	227	/* button mask for report */
 /* selection extent */
 struct tiocl_selection {
 	unsigned short xs;	/* X start */
@@ -28,7 +28,11 @@ struct tiocl_selection {
 
 /* these two don't return a value: they write it back in the type */
 #define TIOCL_GETSHIFTSTATE	6	/* write shift state */
-#define TIOCL_GETMOUSEREPORTING	7	/* write whether mouse event are reported */
+#define TIOCL_GETMOUSEREPORTING	7	/* write which mouse event are reported */
+#define		TIOCL_REPORTBTNPRESS	1	/* report button press only    "9" */
+#define		TIOCL_REPORTRELEASE	2	/* report press and release "1000" */
+#define		TIOCL_REPORTDRAG	3	/* report drag events       "1002" */
+#define		TIOCL_REPORTANYMOVE	4	/* report any movement      "1003" */
 #define TIOCL_SETVESABLANK	10	/* set vesa blanking mode */
 #define TIOCL_SETKMSGREDIRECT	11	/* restrict kernel messages to a vt */
 #define TIOCL_GETFGCONSOLE	12	/* get foreground vt */
Signature · 1 line
2.27.0
maintainer
#2 lore raw

Re: [PATCH v1 1/6] tiocl.h: Change/Add defines for mouse report

Quoted 23 lines · Tammo Block

Add additional defines for mouse event types. The change of the value of TIOCL_SELBUTTONMASK deserves a bit more explanation :

The old value of 15 uses the first 4 bits and sends them unchanged back to userspace if requested by an application. But in fact only the first two bits have ever been used by any daemon or useful at all, as the kernel already knows the status of the shift and alt keys encoded in bits 3 and 4. On the other hand we *do* want to know the status of bits 6-8, encoding button values >3 and mouse move and drag operations.

This change is up- and downwards compatible by masking all spourious bits and leaving only the undisputed parts (bits 1 and 2) untouched.

---
 include/uapi/linux/tiocl.h | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)
include/uapi/linux/tiocl.h +0 -0
index b32acc229024..c862053041e4 100644

include/uapi/linux/tiocl.h line 12

Quoted 5 lines
include/uapi/linux/tiocl.h +1 -1
@@ -9,7 +9,7 @@
 #define 	TIOCL_SELPOINTER	3	/* show the pointer */
 #define 	TIOCL_SELCLEAR	4	/* clear visibility of selection */
 #define 	TIOCL_SELMOUSEREPORT	16	/* report beginning of selection */
-#define 	TIOCL_SELBUTTONMASK	15	/* button mask for report */
+#define 	TIOCL_SELBUTTONMASK	227	/* button mask for report */

0xe3 is more obvious (can be in-brain translated to bits).

If C only had 0b prefix like perl has...

include/uapi/linux/tiocl.h struct tiocl_selection { · line 31

Quoted 9 lines
include/uapi/linux/tiocl.h +1 -1
 /* selection extent */
 struct tiocl_selection {
 	unsigned short xs;	/* X start */
@@ -28,7 +28,11 @@ struct tiocl_selection {
 
 /* these two don't return a value: they write it back in the type */
 #define TIOCL_GETSHIFTSTATE	6	/* write shift state */
-#define TIOCL_GETMOUSEREPORTING	7	/* write whether mouse event are reported */
+#define TIOCL_GETMOUSEREPORTING	7	/* write which mouse event are reported */

s/event/&s/

include/uapi/linux/tiocl.h struct tiocl_selection { · line 38

Quoted 8 lines
include/uapi/linux/tiocl.h +4 -0
+#define		TIOCL_REPORTBTNPRESS	1	/* report button press only    "9" */
+#define		TIOCL_REPORTRELEASE	2	/* report press and release "1000" */
+#define		TIOCL_REPORTDRAG	3	/* report drag events       "1002" */
+#define		TIOCL_REPORTANYMOVE	4	/* report any movement      "1003" */
 #define TIOCL_SETVESABLANK	10	/* set vesa blanking mode */
 #define TIOCL_SETKMSGREDIRECT	11	/* restrict kernel messages to a vt */
 #define TIOCL_GETFGCONSOLE	12	/* get foreground vt */

thanks,

Signature · 2 lines
js
suse labs
#3 lore raw

PATCH 2/6 console_struct.h: Two members for mouse report

In reply to Tammo Block

We need two values to store the status of mouse reporting, both need at least two (vc_protocol_mouse) or three (vc_report_mouse) bits, so use chars.

---
 include/linux/console_struct.h | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)
include/linux/console_struct.h +2 -1
index 153734816b49..dd42287ed553 100644
@@ -132,6 +132,8 @@ struct vc_data {
 	struct pid 	*vt_pid;
 	int		vt_newvt;
 	wait_queue_head_t paste_wait;
+	unsigned char	vc_report_mouse;	/* Which events to report to userspace */
+	unsigned char	vc_protocol_mouse;	/* What protocol to use for report */
 	/* mode flags */
 	unsigned int	vc_disp_ctrl	: 1;	/* Display chars < 32? */
 	unsigned int	vc_toggle_meta	: 1;	/* Toggle high bit? */
@@ -144,7 +146,6 @@ struct vc_data {
 	unsigned int	vc_priv		: 3;
 	unsigned int	vc_need_wrap	: 1;
 	unsigned int	vc_can_do_color	: 1;
-	unsigned int	vc_report_mouse : 2;
 	unsigned char	vc_utf		: 1;	/* Unicode UTF-8 encoding */
 	unsigned char	vc_utf_count;
 		 int	vc_utf_char;
Signature · 1 line
2.27.0
#4 lore raw

PATCH 3/6 vt/vt: Enable mode change via escape sequence

In reply to Tammo Block

This enables userspace to enable one of the mouse protocols and choose one of the new event types by escape sequences.

They are not a bitmasks, but mutually exclusive.

And don't forget to reset protocol value also if resetting vc.

---
 drivers/tty/vt/vt.c | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)
drivers/tty/vt/vt.c +15 -2
index 673177d4e859..e2324d8e4e74 100644
@@ -1896,13 +1896,25 @@ static void set_mode(struct vc_data *vc, int on_off)
 					clr_kbd(vc, decarm);
 				break;
 			case 9:
-				vc->vc_report_mouse = on_off ? 1 : 0;
+				vc->vc_report_mouse = on_off * TIOCL_REPORTBTNPRESS;
 				break;
 			case 25:		/* Cursor on/off */
 				vc->vc_deccm = on_off;
 				break;
 			case 1000:
-				vc->vc_report_mouse = on_off ? 2 : 0;
+				vc->vc_report_mouse = on_off * TIOCL_REPORTRELEASE;
+				break;
+			case 1002:
+				vc->vc_report_mouse = on_off * TIOCL_REPORTDRAG;
+				break;
+			case 1003:
+				vc->vc_report_mouse = on_off * TIOCL_REPORTANYMOVE;
+				break;
+			case 1006:		/* SRG protocol */
+				vc->vc_protocol_mouse = on_off * 1;
+				break;
+			case 1015:		/* URXVT protocol */
+				vc->vc_protocol_mouse = on_off * 2;
 				break;
 			}
 		} else {
@@ -2067,6 +2079,7 @@ static void reset_terminal(struct vc_data *vc, int do_clear)
 	vc->state.charset	= 0;
 	vc->vc_need_wrap	= 0;
 	vc->vc_report_mouse	= 0;
+	vc->vc_protocol_mouse	= 0;
 	vc->vc_utf              = default_utf8;
 	vc->vc_utf_count	= 0;
 
Signature · 1 line
2.27.0
#5 lore raw

PATCH 4/6 vt/vt: Add SRG mouse reporting protocol

In reply to Tammo Block

The SRG protocol indicates a button release by appending a "m" to the report. In this case the button number is not 3 ("release state") but the number of the button that was released. As release event are only reported for the first three buttons, we need to store the number on click events because it is not sent to us from userspace.

We also need to check for the case where no button state change occurred at all (bit 6 set), in this case a value of 3 is OK even in SRG.

Bitmasks for your convenience:
195 - All bits related to any button number
227 - All bits related to button number and "state not changed" bit 252 - All, except low button numbers (left, middle, right button)

---
 drivers/tty/vt/vt.c | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)
drivers/tty/vt/vt.c +16 -3
index e2324d8e4e74..36520f7f0315 100644
@@ -183,6 +183,9 @@ core_param(consoleblank, blankinterval, int, 0444);
 static DECLARE_WORK(console_work, console_callback);
 static DECLARE_WORK(con_driver_unregister_work, con_driver_unregister_callback);
 
+/* remember mouse state */
+unsigned char last_button_pressed = 3;
+
 /*
  * fg_console is the current virtual console,
  * last_console is the last used one,
@@ -1840,11 +1843,21 @@ static inline void respond_ID(struct tty_struct *tty)
 
 void mouse_report(struct tty_struct *tty, int butt, int mrx, int mry)
 {
-	char buf[8];
+	char buf[20];
+	bool rel;
 	int len;
 
-	len = sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
-			(char)('!' + mrx), (char)('!' + mry));
+	if (vc_cons[fg_console].d->vc_protocol_mouse == 1) {	/* SRG*/
+		/* For SRG release events, we send the last clicked button < 3 */
+		rel = ((butt & 195) == 3);
+		if ((butt & 195) < 3)
+			last_button_pressed = butt & 3;
+		if ((butt & 227) == 3)
+			butt = (butt & 252) | last_button_pressed;
+		len = sprintf(buf, "\033[<%d;%d;%d%c", butt, mrx + 1, mry + 1, rel ? 'm' : 'M');
+	} else							/* X10 */
+		len = sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
+				(char)('!' + mrx), (char)('!' + mry));
 	respond_string(buf, len, tty->port);
 }
 
Signature · 1 line
2.27.0
maintainer
#6 lore raw

Re: [PATCH v1 4/6] vt/vt: Add SRG mouse reporting protocol

Quoted 6 lines · Tammo Block

The SRG protocol indicates a button release by appending a "m" to the report. In this case the button number is not 3 ("release state") but the number of the button that was released. As release event are only reported for the first three buttons, we need to store the number on click events because it is not sent to us from userspace.

Quoted 7 lines

We also need to check for the case where no button state change occurred at all (bit 6 set), in this case a value of 3 is OK even in SRG.

Bitmasks for your convenience:
195 - All bits related to any button number
227 - All bits related to button number and "state not changed" bit 252 - All, except low button numbers (left, middle, right button)

Ick, define macros for those (likely in 2/6 where you define the vc_data members holding these bits) and use them below.

Quoted 10 lines
---
 drivers/tty/vt/vt.c | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)
drivers/tty/vt/vt.c +0 -0
index e2324d8e4e74..36520f7f0315 100644

drivers/tty/vt/vt.c core_param(consoleblank, blankinterval, int, 0444); · line 187

Quoted 5 lines
drivers/tty/vt/vt.c +2 -0
@@ -183,6 +183,9 @@ core_param(consoleblank, blankinterval, int, 0444);
 static DECLARE_WORK(console_work, console_callback);
 static DECLARE_WORK(con_driver_unregister_work, con_driver_unregister_callback);
 
+/* remember mouse state */
+unsigned char last_button_pressed = 3;

So this can be static, right? Can this be in mouse_report or is it used elsewhere? If it has to be global, a mouse_ prefix would be good.

Quoted 5 lines
drivers/tty/vt/vt.c +0 -0
 /*
  * fg_console is the current virtual console,
  * last_console is the last used one,
@@ -1840,11 +1843,21 @@ static inline void respond_ID(struct tty_struct *tty)
 

drivers/tty/vt/vt.c static inline void respond_ID(struct tty_struct *tty) · line 1850

Quoted 10 lines
drivers/tty/vt/vt.c +3 -3
 void mouse_report(struct tty_struct *tty, int butt, int mrx, int mry)
 {
-	char buf[8];
+	char buf[20];
+	bool rel;
 	int len;
 
-	len = sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
-			(char)('!' + mrx), (char)('!' + mry));
+	if (vc_cons[fg_console].d->vc_protocol_mouse == 1) {	/* SRG*/

So 1 is SRG, 2 is URXVT, 0 is X10, right? We need constants for those, or maybe enum and switch+case here? No need for the comments here then.

drivers/tty/vt/vt.c static inline void respond_ID(struct tty_struct *tty) · line 1852

Quoted 2 lines
drivers/tty/vt/vt.c +2 -0
+		/* For SRG release events, we send the last clicked button < 3 */
+		rel = ((butt & 195) == 3);

No need for the outer parentheses.

drivers/tty/vt/vt.c static inline void respond_ID(struct tty_struct *tty) · line 1862

Quoted 10 lines
drivers/tty/vt/vt.c +8 -0
+		if ((butt & 195) < 3)
+			last_button_pressed = butt & 3;
+		if ((butt & 227) == 3)
+			butt = (butt & 252) | last_button_pressed;
+		len = sprintf(buf, "\033[<%d;%d;%d%c", butt, mrx + 1, mry + 1, rel ? 'm' : 'M');
+	} else							/* X10 */
+		len = sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
+				(char)('!' + mrx), (char)('!' + mry));
 	respond_string(buf, len, tty->port);
 }

thanks,

Signature · 2 lines
js
suse labs
#7 lore raw

PATCH 5/6 vt/vt: Add URXVT mouse reporting protocol

In reply to Tammo Block

The URXVT protocol easy, all data analog to the old X10.

---
 drivers/tty/vt/vt.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
drivers/tty/vt/vt.c +3 -1
index 36520f7f0315..903c81c52887 100644
@@ -1855,7 +1855,9 @@ void mouse_report(struct tty_struct *tty, int butt, int mrx, int mry)
 		if ((butt & 227) == 3)
 			butt = (butt & 252) | last_button_pressed;
 		len = sprintf(buf, "\033[<%d;%d;%d%c", butt, mrx + 1, mry + 1, rel ? 'm' : 'M');
-	} else							/* X10 */
+	} else if (vc_cons[fg_console].d->vc_protocol_mouse == 2)	/* URXVT*/
+		len = sprintf(buf, "\033[%d;%d;%dM", butt + 32, mrx + 1, mry + 1);
+	else							/* X10 */
 		len = sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
 				(char)('!' + mrx), (char)('!' + mry));
 	respond_string(buf, len, tty->port);
Signature · 1 line
2.27.0
#8 lore raw

PATCH 6/6 Documentation: Describe console mouse reporting

In reply to Tammo Block

This patch adds a description of the kernel interface(s) used for vt console mouse reporting and describes the protocols and bitmasks.

---
 .../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
Documentation/admin-guide/console-mouse-reporting.rst new file +92 -0
new file mode 100644
index 000000000000..11287cb233ba
@@ -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/
+
+
+
+
+
Documentation/admin-guide/index.rst +1 -0
index 58c7f9fc2396..c535902f3851 100644
@@ -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
Signature · 1 line
2.27.0
maintainer
#9 lore raw

Re: [PATCH v1 6/6] Documentation: Describe console mouse reporting

Cc Randy who commented on v0 (you should have done it).

Quoted 30 lines · Tammo Block

This patch adds a description of the kernel interface(s) used for vt console mouse reporting and describes the protocols and bitmasks.

---
 .../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
Documentation/admin-guide/console-mouse-reporting.rst new file +14 -0
new file mode 100644
index 000000000000..11287cb233ba
@@ -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

Documentation/admin-guide/console-mouse-reporting.rst line 24

Quoted 10 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +10 -0
+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

Quoted 6 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +6 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 40

Quoted 10 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +10 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 51

Quoted 11 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +11 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 54

Quoted 3 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +3 -0
+++++++++++++++++++++++++++++++++++
+
+A report is send by a mouse daemon to the kernel via the TIOCLINUX ioctl,

sent (Randy pointed out this one already)

Documentation/admin-guide/console-mouse-reporting.rst line 56

Quoted 2 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +2 -0
+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.

Documentation/admin-guide/console-mouse-reporting.rst line 58

Quoted 2 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +2 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 61

Quoted 3 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +3 -0
+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.

Documentation/admin-guide/console-mouse-reporting.rst line 67

Quoted 6 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +6 -0
+
+- 3,4  : Unused, must be zero. The kernel knows modifier key state anyway.
+- 5    : Always 1, identifies mouse report / TIOCL_SELMOUSEREPORT
+
+Notes
++++++

...

thanks,

Signature · 2 lines
js
suse labs
reviewer
#10 lore raw

Re: [PATCH v1 6/6] Documentation: Describe console mouse reporting

In reply to Tammo Block

Hi--

(duplicating some of Juri's comments)

Quoted 27 lines · Tammo Block

This patch adds a description of the kernel interface(s) used for vt console mouse reporting and describes the protocols and bitmasks.

---
 .../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
Documentation/admin-guide/console-mouse-reporting.rst new file +11 -0
new file mode 100644
index 000000000000..11287cb233ba
@@ -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.

Documentation/admin-guide/console-mouse-reporting.rst line 21

Quoted 10 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +10 -0
+
+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

Documentation/admin-guide/console-mouse-reporting.rst line 24

Quoted 3 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +3 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 31

Quoted 7 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +7 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 40

Quoted 9 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +9 -0
+(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

Documentation/admin-guide/console-mouse-reporting.rst line 41

Quoted 1 line
Documentation/admin-guide/console-mouse-reporting.rst new file +1 -0
+escape sequence, details depend on the chosen format. All of them use one

sequence; details

Documentation/admin-guide/console-mouse-reporting.rst line 51

Quoted 10 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +10 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 54

Quoted 3 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +3 -0
+++++++++++++++++++++++++++++++++++
+
+A report is send by a mouse daemon to the kernel via the TIOCLINUX ioctl,

sent

Documentation/admin-guide/console-mouse-reporting.rst line 58

Quoted 4 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +4 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 60

Quoted 2 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +2 -0
+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

Quoted 13 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +13 -0
+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

Documentation/admin-guide/console-mouse-reporting.rst line 83

Quoted 10 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +10 -0
+
+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

kernels

Documentation/admin-guide/console-mouse-reporting.rst line 92

Quoted 9 lines
Documentation/admin-guide/console-mouse-reporting.rst new file +9 -0
+the upper two bits (modifier keys).
+
+.. [1] https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
+.. [2] https://terminalguide.namepad.de/mouse/
+
+
+
+
+

Drop all those ending blank lines.

thanks.

Signature · 1 line
~Randy