Skip to contentSkip to conversation

Improvements for the -display option

PATCH In review Thomas Huth 2 participants 6 messages Jun 30, 2021 – Jul 5, 2021

lore
Share & tools
lore
#0 lore raw

cover Improvements for the -display option

Fix some oddities of the -display option, deprecate the -no-quit option and improve the documentation.

Thomas Huth (4):
softmmu/vl: Remove obsolete comment about the "frame" parameter
ui: Fix the "-display sdl,window_close=..." parameter
ui: Mark the '-no-quit' option as deprecated
qemu-options: Improve the documentation of the -display options

 docs/system/deprecated.rst | 12 +++++++++
 qemu-options.hx            | 50 +++++++++++++++++++++++++++-----------
 softmmu/vl.c               | 11 ++++++---
 3 files changed, 56 insertions(+), 17 deletions(-)
Signature · 1 line
2.27.0
#1 lore raw

PATCH 1/4 softmmu/vl: Remove obsolete comment about the "frame" parameter

The frame parameter has been removed along with the support for SDL 1.2.

Fixes 09bd7ba9f5 ("Remove deprecated -no-frame option")
---
 softmmu/vl.c | 2 --
 1 file changed, 2 deletions(-)
softmmu/vl.c +0 -2
index d99e2cbdbf..cee6339580 100644
@@ -1062,8 +1062,6 @@ static void parse_display(const char *p)
          * sdl DisplayType needs hand-crafted parser instead of
          * parse_display_qapi() due to some options not in
          * DisplayOptions, specifically:
-         *   - frame
-         *     Already deprecated.
          *   - ctrl_grab + alt_grab
          *     Not clear yet what happens to them long-term.  Should
          *     replaced by something better or deprecated and dropped.
Signature · 1 line
2.27.0
#2 lore raw

PATCH 2/4 ui: Fix the "-display sdl,window_close=..." parameter

In reply to Thomas Huth

According to the QAPI schema, there is a "-" and not a "_" between "window" and "close", and we're also talking about "window-close" in the long parameter description in qemu-options.hx, so we should make sure that we rather use the variant with the "-" by default instead of only allowing the one with the "_" here. The old way still stays enabled for compatibility, but we deprecate it, so that we can switch to a QAPIfied parameter one day more easily.

---
 docs/system/deprecated.rst | 6 ++++++
 qemu-options.hx            | 2 +-
 softmmu/vl.c               | 7 ++++++-
 3 files changed, 13 insertions(+), 2 deletions(-)
docs/system/deprecated.rst +6 -0
index e2e0090878..bb624d3170 100644
@@ -126,6 +126,12 @@ other options have been processed.  This will either have no effect (if
 if they were not given.  The property is therefore useless and should not be
 specified.
 
+``-display sdl,window_close=...`` (since 6.1)
+'''''''''''''''''''''''''''''''''''''''''''''
+
+Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
+an underscore between "window" and "close").
+
 
 QEMU Machine Protocol (QMP) commands
 ------------------------------------
qemu-options.hx +1 -1
index ba3ca9da1d..ae56fa4f28 100644
@@ -1784,7 +1784,7 @@ DEF("display", HAS_ARG, QEMU_OPTION_display,
 #endif
 #if defined(CONFIG_SDL)
     "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
-    "            [,window_close=on|off][,gl=on|core|es|off]\n"
+    "            [,window-close=on|off][,gl=on|core|es|off]\n"
 #endif
 #if defined(CONFIG_GTK)
     "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
softmmu/vl.c +6 -1
index cee6339580..36b761677d 100644
@@ -1089,7 +1089,12 @@ static void parse_display(const char *p)
                 } else {
                     goto invalid_sdl_args;
                 }
-            } else if (strstart(opts, ",window_close=", &nextopt)) {
+            } else if (strstart(opts, ",window_close=", &nextopt) ||
+                       strstart(opts, ",window-close=", &nextopt)) {
+                if (strstart(opts, ",window_close=", NULL)) {
+                    warn_report("window_close with an underscore is deprecated,"
+                                " please use window-close instead.");
+                }
                 opts = nextopt;
                 dpy.has_window_close = true;
                 if (strstart(opts, "on", &nextopt)) {
Signature · 1 line
2.27.0
#3 lore raw

PATCH 3/4 ui: Mark the '-no-quit' option as deprecated

In reply to Thomas Huth

It's just a wrapper around the -display ...,window-close=off parameter, and the name "no-quit" is rather confusing compared to "window-close" (since there are still other means to quit the emulator), so we should rather tell our users to use the "window-close" parameter instead.

While we're at it, update the documentation to state that "-no-quit" is available for GTK, too, not only for SDL.

---
 docs/system/deprecated.rst | 6 ++++++
 qemu-options.hx            | 5 +++--
 softmmu/vl.c               | 2 ++
 3 files changed, 11 insertions(+), 2 deletions(-)
docs/system/deprecated.rst +6 -0
index bb624d3170..70e08baff6 100644
@@ -132,6 +132,12 @@ specified.
 Use ``-display sdl,window-close=...`` instead (i.e. with a minus instead of
 an underscore between "window" and "close").
 
+``-no-quit`` (since 6.1)
+''''''''''''''''''''''''
+
+The ``-no-quit`` is a synonym for ``-display ...,window-close=off`` which
+should be used instead.
+
 
 QEMU Machine Protocol (QMP) commands
 ------------------------------------
qemu-options.hx +3 -2
index ae56fa4f28..c862f1fa57 100644
@@ -1910,10 +1910,11 @@ SRST
 ERST
 
 DEF("no-quit", 0, QEMU_OPTION_no_quit,
-    "-no-quit        disable SDL window close capability\n", QEMU_ARCH_ALL)
+    "-no-quit        disable SDL/GTK window close capability (deprecated)\n", QEMU_ARCH_ALL)
 SRST
 ``-no-quit``
-    Disable SDL window close capability.
+    Disable window close capability (SDL and GTK only). This option is
+    deprecated, please use ``-display ...,window-close=off`` instead.
 ERST
 
 DEF("sdl", 0, QEMU_OPTION_sdl,
softmmu/vl.c +2 -0
index 36b761677d..7dd2d72d0b 100644
@@ -3237,6 +3237,8 @@ void qemu_init(int argc, char **argv, char **envp)
             case QEMU_OPTION_no_quit:
                 dpy.has_window_close = true;
                 dpy.window_close = false;
+                warn_report("-no-quit is deprecated, please use "
+                            "-display ...,window-close=off instead.");
                 break;
             case QEMU_OPTION_sdl:
 #ifdef CONFIG_SDL
Signature · 1 line
2.27.0
#4 lore raw

PATCH 4/4 qemu-options: Improve the documentation of the -display options

In reply to Thomas Huth

The sdl and gtk display options support more parameters than currently documented. Also the "vnc" option got lost during a recent commit, add it again.

Fixes ddc717581c ("Add display suboptions to man pages")
---
 qemu-options.hx | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)
qemu-options.hx +33 -12
index c862f1fa57..8965dabc83 100644
@@ -1783,11 +1783,12 @@ DEF("display", HAS_ARG, QEMU_OPTION_display,
     "-display spice-app[,gl=on|off]\n"
 #endif
 #if defined(CONFIG_SDL)
-    "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off]\n"
-    "            [,window-close=on|off][,gl=on|core|es|off]\n"
+    "-display sdl[,alt_grab=on|off][,ctrl_grab=on|off][,gl=on|core|es|off]\n"
+    "            [,show-cursor=on|off][,window-close=on|off]\n"
 #endif
 #if defined(CONFIG_GTK)
-    "-display gtk[,grab_on_hover=on|off][,gl=on|off]|\n"
+    "-display gtk[,full-screen=on|off][,gl=on|off][,grab-on-hover=on|off]\n"
+    "            [,show-cursor=on|off][,window-close=on|off]\n"
 #endif
 #if defined(CONFIG_VNC)
     "-display vnc=<display>[,<optargs>]\n"
@@ -1824,17 +1825,37 @@ SRST
         application. The Spice server will redirect the serial consoles
         and QEMU monitors. (Since 4.0)
 
-    ``sdl[,window-close=on|off][,gl=on|core|es|off]``
-
+    ``sdl``
         Display video output via SDL (usually in a separate graphics
         window; see the SDL documentation for other possibilities).
+        Valid parameters are:
+
+        ``alt_grab=on|off`` : Use Control+Alt+Shift-g to toggle mouse grabbing
+
+        ``ctrl_grab=on|off`` : Use Right-Control-g to toggle mouse grabbing
+
+        ``gl=on|off|core|es`` : Use OpenGL for displaying
 
-    ``gtk[,grab-on-hover=on|off][,gl=on|off]``
+        ``show-cursor=on|off`` :  Force showing the mouse cursor
+
+        ``window-close=on|off`` : Allow to quit qemu with window close button
+
+    ``gtk``
         Display video output in a GTK window. This interface provides
         drop-down menus and other UI elements to configure and control
-        the VM during runtime.
+        the VM during runtime. Valid parameters are:
+
+        ``full-screen=on|off`` : Start in fullscreen mode
+
+        ``gl=on|off`` : Use OpenGL for displaying
 
-    ``curses [,charset=<encoding>]``
+        ``grab-on-hover=on|off`` : Grab keyboard input on mouse hover
+
+        ``show-cursor=on|off`` :  Force showing the mouse cursor
+
+        ``window-close=on|off`` : Allow to quit qemu with window close button
+
+    ``curses[,charset=<encoding>]``
         Display video output via curses. For graphics device models
         which support a text mode, QEMU can display this output using a
         curses/ncurses interface. Nothing is displayed when the graphics
@@ -1845,11 +1866,14 @@ SRST
         ``charset=CP850`` for IBM CP850 encoding. The default is
         ``CP437``.
 
-    ``egl-headless[,rendernode<file>]``
+    ``egl-headless[,rendernode=<file>]``
         Offload all OpenGL operations to a local DRI device. For any
         graphical display, this display needs to be paired with either
         VNC or SPICE displays.
 
+    ``vnc=<display>``
+        Start a VNC server on display <display>
+
     ``none``
         Do not display video output. The guest will still see an
         emulated graphics card, but its output will not be displayed to
@@ -1857,9 +1881,6 @@ SRST
         that it only affects what is done with video output; -nographic
         also changes the destination of the serial and parallel port
         data.
-
-
-
 ERST
 
 DEF("nographic", 0, QEMU_OPTION_nographic,
Signature · 1 line
2.27.0
#5 lore raw
In reply to Thomas Huth
Quoted 9 lines · Thomas Huth

Fix some oddities of the -display option, deprecate the -no-quit option and improve the documentation.

Thomas Huth (4):
softmmu/vl: Remove obsolete comment about the "frame" parameter
ui: Fix the "-display sdl,window_close=..." parameter
ui: Mark the '-no-quit' option as deprecated
qemu-options: Improve the documentation of the -display options

Quoted 5 lines
  docs/system/deprecated.rst | 12 +++++++++
  qemu-options.hx            | 50 +++++++++++++++++++++++++++-----------
  softmmu/vl.c               | 11 ++++++---
  3 files changed, 56 insertions(+), 17 deletions(-)

Gerd is already on vacation, so I queued this one.

Paolo