vt: Add SRG mouse reporting features
Subsystems (3)
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
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
@@ -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
Jiri Slaby
maintainerRe: [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_SELBUTTONMASKdeserves 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.
Signed-off-by Tammo Block <[email protected]>--- include/uapi/linux/tiocl.h | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-)include/uapi/linux/tiocl.h +0
-0
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
PATCH 2/6 console_struct.h: Two members for mouse report
In reply to Tammo BlockWe 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
@@ -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
PATCH 3/6 vt/vt: Enable mode change via escape sequence
In reply to Tammo BlockThis 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
@@ -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
PATCH 4/6 vt/vt: Add SRG mouse reporting protocol
In reply to Tammo BlockThe 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
@@ -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
Jiri Slaby
maintainerRe: [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
Signed-off-by Tammo Block <[email protected]>--- drivers/tty/vt/vt.c | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-)drivers/tty/vt/vt.c +0
-0
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
-3void 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
PATCH 5/6 vt/vt: Add URXVT mouse reporting protocol
In reply to Tammo BlockThe 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
@@ -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
PATCH 6/6 Documentation: Describe console mouse reporting
In reply to Tammo BlockThis 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
@@ -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
@@ -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
Jiri Slaby
maintainerRe: [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.
Signed-off-by Tammo Block <[email protected]>--- .../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.rstDocumentation/admin-guide/console-mouse-reporting.rst new file +14
-0@@ -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
Randy Dunlap
reviewerRe: [PATCH v1 6/6] Documentation: Describe console mouse reporting
In reply to Tammo BlockHi--
(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.
Signed-off-by Tammo Block <[email protected]>--- .../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.rstDocumentation/admin-guide/console-mouse-reporting.rst new file +11
-0@@ -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