[PATCH v0 0/5] vt: Add SRG mouse reporting features

[PATCH v0 0/5] vt: Add SRG mouse reporting features

[Tammo Block]

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

-- 
2.27.0

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

[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.

Signed-off-by: Tammo Block <tammo.block@gmail.com>
---
 include/linux/console_struct.h |  3 ++-
 include/uapi/linux/tiocl.h     | 24 ++++++++++++++++--------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/include/linux/console_struct.h b/include/linux/console_struct.h
index 24d4c16e3ae0..cfb581eb8b82 100644
--- a/include/linux/console_struct.h
+++ b/include/linux/console_struct.h
@@ -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;
diff --git a/include/uapi/linux/tiocl.h b/include/uapi/linux/tiocl.h
index b32acc229024..df27608648f7 100644
--- a/include/uapi/linux/tiocl.h
+++ b/include/uapi/linux/tiocl.h
@@ -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 */
-- 
2.27.0

Re: [PATCH v0 1/5] Change/add data structures for SRG mouse reporting

[Jiri Slaby]

On 26. 06. 20, 9:22, Tammo Block wrote:
> 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...

> Signed-off-by: Tammo Block <tammo.block@gmail.com>
> ---
>  include/linux/console_struct.h |  3 ++-
>  include/uapi/linux/tiocl.h     | 24 ++++++++++++++++--------
>  2 files changed, 18 insertions(+), 9 deletions(-)
> 
> diff --git a/include/linux/console_struct.h b/include/linux/console_struct.h
> index 24d4c16e3ae0..cfb581eb8b82 100644
> --- a/include/linux/console_struct.h
> +++ b/include/linux/console_struct.h
> @@ -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 :).

>  	unsigned char	vc_utf		: 1;	/* Unicode UTF-8 encoding */
>  	unsigned char	vc_utf_count;
>  		 int	vc_utf_char;
> diff --git a/include/uapi/linux/tiocl.h b/include/uapi/linux/tiocl.h
> index b32acc229024..df27608648f7 100644
> --- a/include/uapi/linux/tiocl.h
> +++ b/include/uapi/linux/tiocl.h
> @@ -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 */

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.

> @@ -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.

>  #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,
-- 
js

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

[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.

Signed-off-by: Tammo Block <tammo.block@gmail.com>
---
 drivers/tty/vt/vt.c | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
index 48a8199f7845..d52ac57034e0 100644
--- a/drivers/tty/vt/vt.c
+++ b/drivers/tty/vt/vt.c
@@ -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 {
-- 
2.27.0

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

[Jiri Slaby]

On 26. 06. 20, 9:22, Tammo Block wrote:
> 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.
> 
> Signed-off-by: Tammo Block <tammo.block@gmail.com>
> ---
>  drivers/tty/vt/vt.c | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
> index 48a8199f7845..d52ac57034e0 100644
> --- a/drivers/tty/vt/vt.c
> +++ b/drivers/tty/vt/vt.c
> @@ -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;

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,
-- 
js
suse labs

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

[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 ...)

Signed-off-by: Tammo Block <tammo.block@gmail.com>
---
 drivers/tty/vt/selection.c | 6 +++---
 drivers/tty/vt/vt.c        | 4 ++--
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/drivers/tty/vt/selection.c b/drivers/tty/vt/selection.c
index 31bb3647a99c..75e7995ddc70 100644
--- a/drivers/tty/vt/selection.c
+++ b/drivers/tty/vt/selection.c
@@ -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;
 	}
 
diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
index d52ac57034e0..5c9c449dc150 100644
--- a/drivers/tty/vt/vt.c
+++ b/drivers/tty/vt/vt.c
@@ -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);
 }
 
-- 
2.27.0

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

[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.

Signed-off-by: Tammo Block <tammo.block@gmail.com>
---
 drivers/tty/vt/vt.c | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
index 5c9c449dc150..af0c58a9b108 100644
--- a/drivers/tty/vt/vt.c
+++ b/drivers/tty/vt/vt.c
@@ -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);
 }
 
-- 
2.27.0

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

[Jiri Slaby]

On 26. 06. 20, 9:23, Tammo Block wrote:
> 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.
> 
> Signed-off-by: Tammo Block <tammo.block@gmail.com>
> ---
>  drivers/tty/vt/vt.c | 26 +++++++++++++++++++++++---
>  1 file changed, 23 insertions(+), 3 deletions(-)
> 
> diff --git a/drivers/tty/vt/vt.c b/drivers/tty/vt/vt.c
> index 5c9c449dc150..af0c58a9b108 100644
> --- a/drivers/tty/vt/vt.c
> +++ b/drivers/tty/vt/vt.c
> @@ -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;

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

> +		butt = butt >> 8;

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);

butt |= 3;

> +			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,
-- 
js
suse labs

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

[Tammo Block]

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

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

[Jiri Slaby]

On 26. 06. 20, 9:23, 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.

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

Thanks for doing this.

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

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

again "sent".

thanks,
-- 
js
suse labs

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

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