From b1613ef56cfa6b81decedc6749334ee7878097f9 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Tue, 1 Jul 2025 14:20:46 -0300 Subject: [PATCH 1/2] add notes about required tools Signed-off-by: Vanessa Maegima --- source/getting-started/install-fioctl/index.rst | 3 +++ source/tutorials/index.rst | 6 ++++++ 2 files changed, 9 insertions(+) diff --git a/source/getting-started/install-fioctl/index.rst b/source/getting-started/install-fioctl/index.rst index 5ee363092..d5df12e29 100644 --- a/source/getting-started/install-fioctl/index.rst +++ b/source/getting-started/install-fioctl/index.rst @@ -203,6 +203,9 @@ After :ref:`Fioctl ` is setup, you can leverage it as a Git credenti This allows pushing to your :ref:`Factory ` repositories. With this, Git knows when you connect to ``source.foundries.io`` and uses Fioctl for authentication when utilizing ``git`` commands. +.. note:: + Make sure ``git`` is installed on your host machine. + Setting Up Git ^^^^^^^^^^^^^^ diff --git a/source/tutorials/index.rst b/source/tutorials/index.rst index 46b0cefff..1f76eb7ee 100644 --- a/source/tutorials/index.rst +++ b/source/tutorials/index.rst @@ -6,6 +6,12 @@ Tutorials Overview The following tutorials will help familiarize you with the workflow for your Factory. As the concepts build upon others, follow them sequentially. +.. important:: + The tutorials assume you have followed the Getting Started and that you have a :ref:`registered device `. + + Make sure you have ``git`` and :ref:`Fioctl ` installed on your host machine. + ``QEMU`` is also required if it is set in your Factory. + :ref:`tutorial-gs-with-docker` introduces ``docker-compose`` apps. Next is :ref:`tutorial-creating-first-target` —learning what a :term:`Target` is through experience is key to using your Factory. From 41a8eb2af58c2a70f25e9dd525055049cf8bff12 Mon Sep 17 00:00:00 2001 From: Vanessa Maegima Date: Tue, 15 Jul 2025 09:36:30 -0300 Subject: [PATCH 2/2] ug: qemu: reorder steps Reorder steps for a straight forward approach to avoid confusion. Signed-off-by: Vanessa Maegima --- source/user-guide/qemu/arm.rst | 4 + source/user-guide/qemu/arm64.rst | 4 + .../qemu/booting-graphically.template | 51 +++++++++++ .../qemu/qemu-instructions.template | 84 +------------------ source/user-guide/qemu/resize.template | 26 ++++++ source/user-guide/qemu/x86_64.rst | 4 + 6 files changed, 93 insertions(+), 80 deletions(-) create mode 100644 source/user-guide/qemu/booting-graphically.template create mode 100644 source/user-guide/qemu/resize.template diff --git a/source/user-guide/qemu/arm.rst b/source/user-guide/qemu/arm.rst index d2af27abb..e710eec82 100644 --- a/source/user-guide/qemu/arm.rst +++ b/source/user-guide/qemu/arm.rst @@ -34,3 +34,7 @@ QEMU CLI .. tip:: You can register your device by following the steps from :ref:`gs-register`. + +.. include:: resize.template + +.. include:: booting-graphically.template diff --git a/source/user-guide/qemu/arm64.rst b/source/user-guide/qemu/arm64.rst index 78adbbe6c..e94999d73 100644 --- a/source/user-guide/qemu/arm64.rst +++ b/source/user-guide/qemu/arm64.rst @@ -61,3 +61,7 @@ QEMU CLI .. tip:: You can register your device by following the steps from :ref:`gs-register`. + +.. include:: resize.template + +.. include:: booting-graphically.template diff --git a/source/user-guide/qemu/booting-graphically.template b/source/user-guide/qemu/booting-graphically.template new file mode 100644 index 000000000..b623d6ac2 --- /dev/null +++ b/source/user-guide/qemu/booting-graphically.template @@ -0,0 +1,51 @@ +Booting Graphically +------------------- + +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:: + + .. group-tab:: Linux + + .. parsed-literal:: + + |QEMU_GUI_FLAGS_LINUX| + + .. group-tab:: macOS + + .. parsed-literal:: + + |QEMU_GUI_FLAGS_MAC| + +Also, do not copy the ``-nographic`` flag at the end of the QEMU CLI below. + +.. 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. + +.. important:: + + Specifying display options in QEMU does not make console-only images graphical. + It just opens a potential graphical output window; interaction remains text-based. + Images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland`` have graphical interfaces. + For further information see: :ref:`LmP Wayland and LmP XWayland `. + + If you are following :ref:`gs-flash-device` and downloading the console image, it will not boot with a graphical interface. + See :ref:`Customizing the Distro ` to know how to build a new Target image. + Ensure that you download the image with the interface, which is usually prefixed with ``lmp-factory-image``. + + Compatibility of the display options may vary, and not all options are supported on every host OS. + Refer to the `QEMU Documentation `_ for more advanced configurations and options. + diff --git a/source/user-guide/qemu/qemu-instructions.template b/source/user-guide/qemu/qemu-instructions.template index 91d949290..d591b9e5d 100644 --- a/source/user-guide/qemu/qemu-instructions.template +++ b/source/user-guide/qemu/qemu-instructions.template @@ -1,14 +1,14 @@ **Artifacts:** -.. important:: - If you are using a prebuilt Target, your artifacts may begin with ``lmp-base-console-image`` instead. - .. parsed-literal:: └── |ARCH| ├── lmp-factory-image-|MACHINE|.wic.gz └── |FIRMWARE_BLOB| +.. important:: + If you are using a prebuilt Target, your artifacts may begin with ``lmp-base-console-image`` instead. + Booting in QEMU --------------- @@ -40,15 +40,7 @@ Booting in QEMU .. parsed-literal:: gunzip lmp-factory-image-|MACHINE|.wic.gz -#. `Optional`. Create and resize a qcow2 image: - - .. parsed-literal:: - qemu-img create -f qcow2 -F raw -b lmp-factory-image-|MACHINE|.wic |MACHINE|\_device1.qcow2 - qemu-img resize -f qcow2 |MACHINE|\_device1.qcow2 8G - - The above example creates and then resizes to 8G—set to meet your needs. - #. The directory tree should now look like this: .. parsed-literal:: @@ -56,80 +48,12 @@ Booting in QEMU lmp-qemu/ └── |ARCH| ├── lmp-factory-image-|MACHINE|.wic - ├── |MACHINE|\_device1.qcow2 # optional, needed if resizing is required └── |FIRMWARE_BLOB| -#. Run the QEMU script below against the artifacts inside of ``lmp-qemu/``. +#. Run the QEMU script in the next section against the artifacts inside of ``lmp-qemu/``. You can save this as ``run.sh`` inside the directory for convenience. -.. important:: - Use .qcow2 if you wish to change the QEMU disk size, or if you are looking to emulate multiple devices. - Each image converted and subsequently run with QEMU will be recognized as a distinct device. - If you are using the qcow2 image, change the script so that: - - * ``file=`` is set as the qcow2 image name, i.e., |MACHINE|\_device1.qcow2 - * ``format=raw`` is replaced with ``format=qcow2``. - - For example, replacing `MACHINE` appropriately: - - .. parsed-literal:: - - |QEMU_COW| - .. note:: The QEMU CLI passes the necessary flags and parameters to the appropriate qemu-system command. This includes path to the image, CPU, network, and other device information. For specifics, consult `QEMU's Documentation. `_ - -Booting Graphically -------------------- - -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:: - - .. group-tab:: Linux - - .. parsed-literal:: - - |QEMU_GUI_FLAGS_LINUX| - - .. group-tab:: macOS - - .. parsed-literal:: - - |QEMU_GUI_FLAGS_MAC| - -Also, do not copy the ``-nographic`` flag at the end of the QEMU CLI below. - -.. 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. - - -.. important:: - - Specifying display options in QEMU does not make console-only images graphical. - It just opens a potential graphical output window; interaction remains text-based. - Images created with ``DISTRO=lmp-xwayland`` or ``DISTRO=lmp-wayland`` have graphical interfaces. - For further information see: :ref:`LmP Wayland and LmP XWayland `. - - If you are following :ref:`gs-flash-device` and downloading the console image, it will not boot with a graphical interface. - See :ref:`Customizing the Distro ` to know how to build a new Target image. - Ensure that you download the image with the interface, which is usually prefixed with ``lmp-factory-image``. - - Compatibility of the display options may vary, and not all options are supported on every host OS. - Refer to the `QEMU Documentation `_ for more advanced configurations and options. - diff --git a/source/user-guide/qemu/resize.template b/source/user-guide/qemu/resize.template new file mode 100644 index 000000000..57241869d --- /dev/null +++ b/source/user-guide/qemu/resize.template @@ -0,0 +1,26 @@ +Image Resizing +^^^^^^^^^^^^^^ + +If required, the Factory image can be resized for more space available. + +Create and resize a ``qcow2`` image: + +.. parsed-literal:: + qemu-img create -f qcow2 -F raw -b lmp-factory-image-|MACHINE|.wic |MACHINE|\_device1.qcow2 + qemu-img resize -f qcow2 |MACHINE|\_device1.qcow2 8G + +The above example creates and then resizes to 8G—set to meet your needs. + +This requires changes to the script so that: + + * ``file=`` is set as the qcow2 image name, i.e., |MACHINE|\_device1.qcow2 + * ``format=raw`` is replaced with ``format=qcow2``. + +So for example, the CLI command to run the resized image is: + +.. parsed-literal:: + |QEMU_COW| + +.. important:: + Use ``qcow2`` if you wish to change the QEMU disk size, or if you are looking to emulate multiple devices. + Each image converted and subsequently run with QEMU will be recognized as a distinct device. diff --git a/source/user-guide/qemu/x86_64.rst b/source/user-guide/qemu/x86_64.rst index df4d89132..00f48caec 100644 --- a/source/user-guide/qemu/x86_64.rst +++ b/source/user-guide/qemu/x86_64.rst @@ -31,3 +31,7 @@ QEMU CLI .. tip:: You can register your device following the steps from :ref:`gs-register`. + +.. include:: resize.template + +.. include:: booting-graphically.template