Enhance Documentation: Clarifications and Helpers for Graphical Booti…

…ng in QEMU

Signed-off-by: Camila Macedo <[email protected]>

Co-authored-by: Katrina Prosise <[email protected]>

source/reference-manual/linux/linux-distro.rst

@@ -48,11 +48,53 @@ 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.
 
 .. _term-DISTRO: https://docs.yoctoproject.org/kirkstone/ref-manual/variables.html#term-DISTRO
 
 .. _Poky: https://www.yoctoproject.org/software-overview/reference-distribution/
+
+Changing The Default Distro
+*****************************
+
+The Following is an example on how to build new targets with these images:
+
+1. Update your factory config:
+
+.. code-block:: shell
+
+    git clone https://source.foundries.io/factories/<factory>/ci-scripts.git
+    cd ci-scripts
+    vi factory-config.yml
+
+2. Add the distro under `LmP`:
+
+.. code-block:: yaml
+
+    worker_tag: "amd64-partner-aws"
+    params:
+        IMAGE: lmp-factory-image
+        SSTATE_CACHE_MIRROR: ""
+        DOCKER_COMPOSE_APP: "1"
+        DISTRO: "lmp-xwayland"
+
+3. Commit and push the changes:
+
+.. code-block:: shell
+
+    git add .
+    git commit -m "Adding lmp-xwayland as base for my factory"
+    git push
+
+4. Changes into the ``ci-script`` repository don't auto-trigger builds. Push a commit in ``lmp-manifest`` or ``meta-subscriber-overrides``:
+
+.. code-block:: shell
+
+    git clone https://source.foundries.io/factories/<factory>/lmp-manifest.git
+    cd lmp-manifest
+    git commit -m "trigger build" --allow-empty

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 how to boot QEMU with an OpenGL capable virtual GPU—required for Wayland/Weston.
+To check the available options for your system, use the ``-display help`` flag:
+
+.. 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 also utilize the option ``-display default``.
+    This 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 does not make console-only images graphical. It just opens a potential graphical
+   output window. Interaction is mainly text-based. The images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland``
+   have graphical interfaces.
+
+   If you are following :ref:`gs-flash-device` and downloading the console image, it will not 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 is usually
+   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.
+