Skip to contentSkip to conversation

vt: Add SRG mouse reporting features

PATCH In review Tammo Block 3 participants 11 messages Jun 26, 2020

Subsystems (3)
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 kernel console.

The linux virtual console has support for mouse reporting since 1994 or so, but the kernel only supports the original X10 ("9") and X11 ("1000") style standard protocols. To support more protocols these patches expand the kernel structures in a downwards compatible way, see the last patch for detailed documentation and [1] or [2] for a list and description of alls the bits of the various protocols, as well as their limitations.

This new feature offers the following advantages :

1.) XTerm already supports all of this and as most (all?) TUI software with
mouse support is compatible and tested with xterm, they will also work with the kernel console. Programs will work out of the box with this (if the mouse daemon supports it) and there is no need to change them.
2.) All protocols also work via ssh while the gpm protocol does not, because
gpm uses a local socket (/dev/gpmdata) to communicate with the clients.
3.) Even the Microsoft Console does support these xterm like protocols, we
should not let the linux console fall behind! ;-)

TTBOMK the *only* user of any of the mouse reporting interface today is "consolation" [3]. The well known GPM does not support mouse reporting at all (yet), see [4] for details. Of course the mouse daemons have to be adapted too, but they will continue to work as before if they are not adapted.

[4] also originally gave the reason for these patches.

Kind regards,
Tammo

[1] https://terminalguide.namepad.de/mouse/
[2] https://invisible-island.net/xterm/ctlseqs/ctlseqs.html#h2-Mouse-Tracking
[3] https://salsa.debian.org/consolation-team/consolation/
[4] https://github.com/telmich/gpm/issues/29

Tammo Block (5):
Change/add data structures for SRG mouse reporting Make it possible to enable/disable SRG mouse reporting Check for SRG protocol and move bit masking Add support for SRG report output format
Add Documentation for console mouse reporting

 .../admin-guide/console-mouse-reporting.rst   | 82 +++++++++++++++++++
 Documentation/admin-guide/index.rst           |  1 +
 drivers/tty/vt/selection.c                    |  6 +-
 drivers/tty/vt/vt.c                           | 39 +++++++--
 include/linux/console_struct.h                |  3 +-
 include/uapi/linux/tiocl.h                    | 24 ++++--
 6 files changed, 138 insertions(+), 17 deletions(-)
 create mode 100644 Documentation/admin-guide/console-mouse-reporting.rst
Signature · 1 line
2.27.0
#1 lore raw

PATCH 1/5 Change/add data structures for SRG mouse reporting

This extends the data structures and defines needed for additional mouse reporting features. If URXVT and UTF8 reports should be supported in the future, vc_proto_mouse would need another bit.

---
 include/linux/console_struct.h |  3 ++-
 include/uapi/linux/tiocl.h     | 24 ++++++++++++++++--------
 2 files changed, 18 insertions(+), 9 deletions(-)
include/linux/console_struct.h +2 -1
index 24d4c16e3ae0..cfb581eb8b82 100644
@@ -122,7 +122,8 @@ 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 int	vc_report_mouse : 3;
+	unsigned int	vc_proto_mouse  : 1;
 	unsigned char	vc_utf		: 1;	/* Unicode UTF-8 encoding */
 	unsigned char	vc_utf_count;
 		 int	vc_utf_char;
include/uapi/linux/tiocl.h +16 -8
index b32acc229024..df27608648f7 100644
@@ -3,13 +3,17 @@
 #define _LINUX_TIOCL_H
 
 #define TIOCL_SETSEL	2	/* set a selection */
-#define 	TIOCL_SELCHAR	0	/* select characters */
-#define 	TIOCL_SELWORD	1	/* select whole words */
-#define 	TIOCL_SELLINE	2	/* select whole lines */
-#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_SELCHAR	0	/* select characters */
+#define		TIOCL_SELWORD	1	/* select whole words */
+#define		TIOCL_SELLINE	2	/* select whole lines */
+#define		TIOCL_SELPOINTER	3	/* show the pointer */
+#define		TIOCL_SELCLEAR	4	/* clear visibility of selection */
+#define		TIOCL_SELMOUSEREPORT	16	/* send X10 mouse report */
+#define		TIOCL_SELBUTTONMASK	15	/* button mask for X10 report */
+#define		TIOCL_SELSRGREPORT	32	/* send SRG mouse report */
+#define		TIOCL_SELSRGRELEASE	128	/* SRG report is release event */
+#define		TIOCL_SELSRGMASK	(255 << 8)	/* mask for SRG report */
+
 /* selection extent */
 struct tiocl_selection {
 	unsigned short xs;	/* X start */
@@ -28,7 +32,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 to be reported */
+#define		TIOCL_REPORTBTNPRESS	1	/* report button press only    "9" */
+#define		TIOCL_REPORTRELEASE	2	/* report press and release "1000" */
+#define		TIOCL_REPORTDRAG	5	/* report drag events       "1002" */
+#define		TIOCL_REPORTANYMOVE	6	/* 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 v0 1/5] Change/add data structures for SRG mouse reporting

Quoted 3 lines · Tammo Block

This extends the data structures and defines needed for additional mouse reporting features. If URXVT and UTF8 reports should be supported in the future, vc_proto_mouse would need another bit.

Just a global remark: I have just rewritten a large part of the vt code. You might need to rebase on the top of tty-next...

Quoted 11 lines
---
 include/linux/console_struct.h |  3 ++-
 include/uapi/linux/tiocl.h     | 24 ++++++++++++++++--------
 2 files changed, 18 insertions(+), 9 deletions(-)
include/linux/console_struct.h +0 -0
index 24d4c16e3ae0..cfb581eb8b82 100644

include/linux/console_struct.h struct vc_data { · line 126

Quoted 6 lines
include/linux/console_struct.h +2 -1
@@ -122,7 +122,8 @@ 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 int	vc_report_mouse : 3;
+	unsigned int	vc_proto_mouse  : 1;

bitfields... The generated code is so bad (it does masks, shifts and ANDs in assembly), so please avoid them and define the new members the standard way. I.e. unsigned char if 8 bits are enough, bool for one bit and so on. The price is larger structure, but we can afford 5 more bits per virt console, I think. Provided there is a very limited number them -- this is not "struct page" after all :).

Quoted 18 lines
include/linux/console_struct.h +0 -0
 	unsigned char	vc_utf		: 1;	/* Unicode UTF-8 encoding */
 	unsigned char	vc_utf_count;
 		 int	vc_utf_char;
include/uapi/linux/tiocl.h +0 -7
index b32acc229024..df27608648f7 100644
@@ -3,13 +3,17 @@
 #define _LINUX_TIOCL_H
 
 #define TIOCL_SETSEL	2	/* set a selection */
-#define 	TIOCL_SELCHAR	0	/* select characters */
-#define 	TIOCL_SELWORD	1	/* select whole words */
-#define 	TIOCL_SELLINE	2	/* select whole lines */
-#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 */

include/uapi/linux/tiocl.h line 15

Quoted 10 lines
include/uapi/linux/tiocl.h +10 -0
+#define		TIOCL_SELCHAR	0	/* select characters */
+#define		TIOCL_SELWORD	1	/* select whole words */
+#define		TIOCL_SELLINE	2	/* select whole lines */
+#define		TIOCL_SELPOINTER	3	/* show the pointer */
+#define		TIOCL_SELCLEAR	4	/* clear visibility of selection */
+#define		TIOCL_SELMOUSEREPORT	16	/* send X10 mouse report */
+#define		TIOCL_SELBUTTONMASK	15	/* button mask for X10 report */
+#define		TIOCL_SELSRGREPORT	32	/* send SRG mouse report */
+#define		TIOCL_SELSRGRELEASE	128	/* SRG report is release event */
+#define		TIOCL_SELSRGMASK	(255 << 8)	/* mask for SRG report */

This right shift of all of them feels like too much right. Why do you do it? And if you do it, do it in a separate patch. It makes this one complicated to review.

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

Quoted 10 lines
include/uapi/linux/tiocl.h +5 -1
@@ -28,7 +32,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 to be reported */
+#define		TIOCL_REPORTBTNPRESS	1	/* report button press only    "9" */
+#define		TIOCL_REPORTRELEASE	2	/* report press and release "1000" */
+#define		TIOCL_REPORTDRAG	5	/* report drag events       "1002" */
+#define		TIOCL_REPORTANYMOVE	6	/* report any movement      "1003" */

Dtto.

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

Quoted 3 lines
include/uapi/linux/tiocl.h +0 -0
 #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 · 1 line
js
#3 lore raw

PATCH 2/5 Make it possible to enable/disable SRG mouse reporting

In reply to Tammo Block

The report protocol stored in vc_report_mouse is not a bitmask, the protocols are mutually exclusive, last one wins. Values are chosen to maximize compatibility.

---
 drivers/tty/vt/vt.c | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)
drivers/tty/vt/vt.c +11 -2
index 48a8199f7845..d52ac57034e0 100644
@@ -1890,13 +1890,22 @@ 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 : 0;
 				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 : 0;
+				break;
+			case 1002:
+				vc->vc_report_mouse = on_off ? TIOCL_REPORTDRAG : 0;
+				break;
+			case 1003:
+				vc->vc_report_mouse = on_off ? TIOCL_REPORTANYMOVE : 0;
+				break;
+			case 1006:
+				vc->vc_proto_mouse = on_off ? 1 : 0;
 				break;
 			}
 		} else {
Signature · 1 line
2.27.0
maintainer
#4 lore raw

Re: [PATCH v0 2/5] Make it possible to enable/disable SRG mouse reporting

Quoted 25 lines · Tammo Block

The report protocol stored in vc_report_mouse is not a bitmask, the protocols are mutually exclusive, last one wins. Values are chosen to maximize compatibility.

---
 drivers/tty/vt/vt.c | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)
drivers/tty/vt/vt.c +1 -2
index 48a8199f7845..d52ac57034e0 100644
@@ -1890,13 +1890,22 @@ 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 : 0;
 				break;
 			case 25:		/* Cursor on/off */
 				vc->vc_deccm = on_off;
 				break;
 			case 1000:
-				vc->vc_report_mouse = on_off ? 2 : 0;

drivers/tty/vt/vt.c static void set_mode(struct vc_data *vc, int on_off) · line 1908

Quoted 10 lines
drivers/tty/vt/vt.c +10 -0
+				vc->vc_report_mouse = on_off ? TIOCL_REPORTRELEASE : 0;
+				break;
+			case 1002:
+				vc->vc_report_mouse = on_off ? TIOCL_REPORTDRAG : 0;
+				break;
+			case 1003:
+				vc->vc_report_mouse = on_off ? TIOCL_REPORTANYMOVE : 0;
+				break;
+			case 1006:
+				vc->vc_proto_mouse = on_off ? 1 : 0;

So simply:
vc->vc_proto_mouse = on_off;

The others could be "on_off * TIOCL_XXX", but I don't think it would improve anything.

thanks,

Signature · 2 lines
js
suse labs
#5 lore raw

PATCH 3/5 Check for SRG protocol and move bit masking

In reply to Tammo Block

Add a check for the new SRG protocol bit and move masking of report to report_mouse function (Otherwise all SRG information is lost ...)

---
 drivers/tty/vt/selection.c | 6 +++---
 drivers/tty/vt/vt.c        | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)
drivers/tty/vt/selection.c +3 -3
index 31bb3647a99c..75e7995ddc70 100644
@@ -331,9 +331,9 @@ static int vc_selection(struct vc_data *vc, struct tiocl_selection *v,
 	v->xe = min_t(u16, v->xe - 1, vc->vc_cols - 1);
 	v->ye = min_t(u16, v->ye - 1, vc->vc_rows - 1);
 
-	if (mouse_reporting() && (v->sel_mode & TIOCL_SELMOUSEREPORT)) {
-		mouse_report(tty, v->sel_mode & TIOCL_SELBUTTONMASK, v->xs,
-			     v->ys);
+	if (mouse_reporting() && (v->sel_mode &
+		(TIOCL_SELMOUSEREPORT | TIOCL_SELSRGREPORT))) {
+		mouse_report(tty, v->sel_mode, v->xs, v->ys);
 		return 0;
 	}
 
drivers/tty/vt/vt.c +2 -2
index d52ac57034e0..5c9c449dc150 100644
@@ -1837,8 +1837,8 @@ void mouse_report(struct tty_struct *tty, int butt, int mrx, int mry)
 {
 	char buf[8];
 
-	sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt), (char)('!' + mrx),
-		(char)('!' + mry));
+	sprintf(buf, "\033[M%c%c%c", (char)(' ' + (butt & TIOCL_SELBUTTONMASK)),
+		(char)('!' + mrx), (char)('!' + mry));
 	respond_string(buf, tty->port);
 }
 
Signature · 1 line
2.27.0
#6 lore raw

PATCH 4/5 Add support for SRG report output format

In reply to Tammo Block

Add SRG ("1005") style mouse reports. Always use them to create a report to userspace if they are available because they may contain more information (e.g. scroll wheel events).

Do not send reports at all if report information is not sufficient.

---
 drivers/tty/vt/vt.c | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)
drivers/tty/vt/vt.c +23 -3
index 5c9c449dc150..af0c58a9b108 100644
@@ -1835,10 +1835,30 @@ 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];
+	char rel;
 
-	sprintf(buf, "\033[M%c%c%c", (char)(' ' + (butt & TIOCL_SELBUTTONMASK)),
-		(char)('!' + mrx), (char)('!' + mry));
+	if (butt & TIOCL_SELSRGREPORT) {
+		rel = (butt & TIOCL_SELSRGRELEASE) ? 1 : 0;
+		butt = butt >> 8;
+
+		if (vc_cons[fg_console].d->vc_proto_mouse) {
+			sprintf(buf, "\033[<%d;%d;%d%c", butt, mrx + 1, mry + 1, rel ? 'm' : 'M');
+		} else {
+			if (rel)
+				butt = (3 | butt);
+			sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
+				(char)('!' + mrx), (char)('!' + mry));
+		}
+	} else {
+		/* Compatibility for older protocol */
+		if (vc_cons[fg_console].d->vc_proto_mouse)
+			return;
+		if (vc_cons[fg_console].d->vc_report_mouse > 2)
+			return;
+		sprintf(buf, "\033[M%c%c%c", (char)(' ' + (butt & TIOCL_SELBUTTONMASK)),
+			(char)('!' + mrx), (char)('!' + mry));
+	}
 	respond_string(buf, tty->port);
 }
 
Signature · 1 line
2.27.0
maintainer
#7 lore raw

Re: [PATCH v0 4/5] Add support for SRG report output format

Quoted 16 lines · Tammo Block

Add SRG ("1005") style mouse reports. Always use them to create a report to userspace if they are available because they may contain more information (e.g. scroll wheel events).

Do not send reports at all if report information is not sufficient.

---
 drivers/tty/vt/vt.c | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)
drivers/tty/vt/vt.c +0 -0
index 5c9c449dc150..af0c58a9b108 100644

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

Quoted 6 lines
drivers/tty/vt/vt.c +2 -1
@@ -1835,10 +1835,30 @@ 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];
+	char rel;

bool rel;

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

Quoted 5 lines
drivers/tty/vt/vt.c +2 -2
-	sprintf(buf, "\033[M%c%c%c", (char)(' ' + (butt & TIOCL_SELBUTTONMASK)),
-		(char)('!' + mrx), (char)('!' + mry));
+	if (butt & TIOCL_SELSRGREPORT) {
+		rel = (butt & TIOCL_SELSRGRELEASE) ? 1 : 0;

Ternary operator superfluous.

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

Quoted 1 line
drivers/tty/vt/vt.c +1 -0
+		butt = butt >> 8;

butt >>= 8;

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

Quoted 6 lines
drivers/tty/vt/vt.c +6 -0
+
+		if (vc_cons[fg_console].d->vc_proto_mouse) {
+			sprintf(buf, "\033[<%d;%d;%d%c", butt, mrx + 1, mry + 1, rel ? 'm' : 'M');
+		} else {
+			if (rel)
+				butt = (3 | butt);

butt |= 3;

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

Quoted 13 lines
drivers/tty/vt/vt.c +12 -0
+			sprintf(buf, "\033[M%c%c%c", (char)(' ' + butt),
+				(char)('!' + mrx), (char)('!' + mry));
+		}
+	} else {
+		/* Compatibility for older protocol */
+		if (vc_cons[fg_console].d->vc_proto_mouse)
+			return;
+		if (vc_cons[fg_console].d->vc_report_mouse > 2)
+			return;
+		sprintf(buf, "\033[M%c%c%c", (char)(' ' + (butt & TIOCL_SELBUTTONMASK)),
+			(char)('!' + mrx), (char)('!' + mry));
+	}
 	respond_string(buf, tty->port);

thanks,

Signature · 2 lines
js
suse labs
#8 lore raw

PATCH 5/5 Add Documentation for console mouse reporting

In reply to Tammo Block

This patch adds a description of the kernel interface(s) used for mouse reporting and compares the old and new bitmask layout.

---
 .../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
Documentation/admin-guide/console-mouse-reporting.rst new file +82 -0
new file mode 100644
index 000000000000..799288295655
@@ -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/
+
+
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 v0 5/5] Add Documentation for console mouse reporting

Quoted 2 lines · Tammo Block

This patch adds a description of the kernel interface(s) used for mouse reporting and compares the old and new bitmask layout.

<irony>
Documentation for the vt code? Phew.
</irony>

Thanks for doing this.

Quoted 12 lines
---
 .../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
Documentation/admin-guide/console-mouse-reporting.rst new file +0 -0
new file mode 100644
index 000000000000..799288295655

...

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

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

To me -- a non-native -- it looks like s/send/sent/?

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

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

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

again "sent".

thanks,

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

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

In reply to Tammo Block
Quoted 16 lines · Tammo Block

This patch adds a description of the kernel interface(s) used for mouse reporting and compares the old and new bitmask layout.

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

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

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

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

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

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

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

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

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

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

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

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

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

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