Enhance Documentation: Clarifications and Helpers for Graphical Booti…

…ng in QEMU Signed-off-by: Camila Macedo <[email protected]>
foundriesio · Oct 2, 2023 · 4361346 · 4361346
1 parent 288bd30
commit 4361346
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 2 deletions.
diff --git a/source/reference-manual/linux/linux-distro.rst b/source/reference-manual/linux/linux-distro.rst
@@ -48,8 +48,10 @@ LmP MFGTools
 
 The distro used to generate the ``mfgtool-files`` artifacts which provide the deploy and update tool for some machines (i.MX family).
 
+.. _ref-lmp-wayland-xwayland:
+
 LmP Wayland and LmP XWayland
-****************************
+*********************************
 
 The distros which provide Wayland and XWayland support on top of ``lmp`` distro.
 

diff --git a/source/reference-manual/qemu/qemu-instructions.template b/source/reference-manual/qemu/qemu-instructions.template
@@ -95,7 +95,18 @@ Booting in QEMU
 Booting Graphically
 -------------------
 
-In order to boot QEMU with an OpenGL capable virtual GPU (required for Wayland/Weston), add the following flags to the QEMU CLI:
+This section shows a general guideline to boot QEMU with an OpenGL capable virtual GPU (required for Wayland/Weston).
+To check the available options in your system use the flag ``-display help``, i.e.:
+
+.. parsed-literal::
+   $ qemu-system-aarch64 -display help
+   Available display backend types:
+   none
+   curses
+   cocoa
+   dbus
+
+In general, adding the following flags to the QEMU CLI should work:
 
 .. tabs::
 
@@ -111,7 +122,28 @@ In order to boot QEMU with an OpenGL capable virtual GPU (required for Wayland/W
 
          |QEMU_GUI_FLAGS_MAC|
 
+.. note::
+
+    You can utilize the option ``-display default``
+       It attempts to use the default display type corresponding to the operating system on which you are running the command.
+
 .. note::
 
     Do not copy the ``-nographic`` flag at the end of the QEMU CLI below.
 
+.. important::
+
+   Specifying display options in QEMU doesn't make console-only images graphical. It just opens a potential graphical
+   output window. Interaction is mainly text-based. Only ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland``
+   images have graphical interfaces.
+
+   If you are following :ref:`gs-flash-device` and downloading the console image, it won't boot with a
+   graphical interface. See :ref:`LmP Wayland and LmP XWayland <ref-lmp-wayland-xwayland>` to build a new
+   target image. Also, ensure that you download the image with the interface, which usually is
+   prefixed with ``lmp-factory-image``.
+
+.. important::
+
+   Compatibility of the display options may vary, and not all options are supported on every host OS.
+   Refer to the `QEMU Documentation <https://www.qemu.org/>`_ for more advanced configurations and options.
+