diff --git a/source/_static/qemu/example_factory_arm64.png b/source/_static/qemu/example_factory_arm64.png new file mode 100644 index 000000000..fc7bf638b Binary files /dev/null and b/source/_static/qemu/example_factory_arm64.png differ diff --git a/source/_static/qemu/example_login.png b/source/_static/qemu/example_login.png new file mode 100644 index 000000000..89e247225 Binary files /dev/null and b/source/_static/qemu/example_login.png differ diff --git a/source/_static/qemu/example_required_artefacts.png b/source/_static/qemu/example_required_artefacts.png new file mode 100644 index 000000000..23198b20d Binary files /dev/null and b/source/_static/qemu/example_required_artefacts.png differ diff --git a/source/getting-started/emulation-with-qemu/index.rst b/source/getting-started/emulation-with-qemu/index.rst new file mode 100644 index 000000000..d7e962586 --- /dev/null +++ b/source/getting-started/emulation-with-qemu/index.rst @@ -0,0 +1,111 @@ +.. _gs-emulation-with-qemu: + +Device Emulation Using QEMU +============================= + +.. note:: + + This tutorial is designed to assist you in getting started with using QEMU to emulate devices on your desktop. Please note that we are selecting a specific FoundriesFactory® to establish an environment for experimenting with the Foundries.io™ solution. This approach will enable you to engage with subsequent tutorials and enhance your skills. + +Prerequisites and Pre-Work +--------------------------- + + - Ensure that you have installed `QEMU `_ 5.2 or later. + - Create a :ref:`ref-factory` for the platform ``QEMU Arm 64 bit`` as described in the guide :ref:`gs-select-platform`: + +.. figure:: /_static/qemu/example_factory_arm64.png + :width: 900 + :align: center + :alt: QEMU Arm 64 bit example factory + +Emulating Device +-------------------------- + +1. Go to the `Targets` tab of your Factory and download the ``lmp-base-console-image-qemuarm64-secureboot.wic.gz`` image and the ``flash.bin``: + +.. figure:: /_static/qemu/example_required_artefacts.png + :width: 900 + :align: center + :alt: Artifacts which are required to run the image with QEMU + +2. Make a directory for the artifacts and cd into it: + +.. code-block:: shell + + mkdir -p lmp-qemu/arm64 + cd lmp-qemu/arm64 + +3. Copy the Artifacts to the ``lmp-qemu/arm64`` directory : + +.. code-block:: shell + + cp /lmp-base-console-image-qemuarm64-secureboot.wic.gz . + cp /flash.bin . + +4. Decompress the image: + +.. code-block:: shell + + gunzip lmp-base-console-image-qemuarm64-secureboot.wic.gz + +5. Convert the Disk to QCOW2 Format: + +Use ``qemu-img`` to convert your raw disk image to the QCOW2 format. This step can sometimes make the image more amenable to virtualization. + +.. code-block:: shell + + qemu-img convert -f raw -O qcow2 lmp-base-console-image-qemuarm64-secureboot.wic lmp-base-console-image-qemuarm64-secureboot.qcow2 + +6. Resize the Image: + +Resize the new QCOW2 image to a size that’s a multiple of the sector size. Let’s resize it to 4GB for simplicity. + +.. code-block:: shell + + qemu-img resize lmp-base-console-image-qemuarm64-secureboot.qcow2 4G + +7. Run QEMU with the New Image: + +Once you’ve converted and resized the image, you can then use it with your QEMU command. + +.. code-block:: shell + + qemu-system-aarch64 \ + -m 2048 \ + -cpu cortex-a57 \ + -smp 2 \ + -machine acpi=off \ + -bios flash.bin \ + -device virtio-net-device,netdev=net0,mac=52:54:00:12:35:02 \ + -device virtio-serial-device \ + -drive id=disk0,file=lmp-base-console-image-qemuarm64-secureboot.qcow2,if=none,format=qcow2 \ + -device virtio-blk-device,drive=disk0 \ + -netdev user,id=net0,hostfwd=tcp::2222-:22 \ + -object rng-random,filename=/dev/urandom,id=rng0 \ + -device virtio-rng-pci,rng=rng0 \ + -chardev null,id=virtcon \ + -machine virt,secure=on \ + -nographic + +8. Log into the booted system: + + By default, the ``username`` and ``password`` to log in your device after boot are ``fio/fio``. We recommend changing them once you are in development. + + .. figure:: /_static/qemu/example_login.png + :width: 900 + :align: center + :alt: Login + +.. note:: + + If you are not prompted for login, press ``Enter`` to check if it gets displayed. + +.. note:: + + If you encounter a QEMU terminal where common commands like ``ls`` are unresponsive, it may indicate an issue. A missing login prompt likely means that your image did not boot successfully. + For this specific platform, we use the ``-bios=flash.bin`` flag to boot the system. However, the flags and configurations may vary based on the selected platform. + +Next Step +-------------------------- + +At this point, you have successfully set up the device. You are now able to :ref:`gs-register` and proceed with the following tutorials. diff --git a/source/getting-started/flash-device/index.rst b/source/getting-started/flash-device/index.rst index aca4f4fae..64a1e9a52 100644 --- a/source/getting-started/flash-device/index.rst +++ b/source/getting-started/flash-device/index.rst @@ -21,6 +21,10 @@ Prerequisites and Pre-Work - Ethernet cable (if choosing Wired) - Console access to your hardware via UART serial (if choosing WiFi) +.. note:: + + If you are just getting started and prefer to emulate the device rather than using a physical board, make sure to refer to the guide :ref:`gs-emulation-with-qemu`. Following this guide will lead you through "Flashing the Image" just like this guide, enabling you to proceed with the subsequent steps to :ref:`gs-register`. + .. _gs-download: Downloading the LmP System Image diff --git a/source/index.rst b/source/index.rst index ea4c67c3a..5b226c452 100644 --- a/source/index.rst +++ b/source/index.rst @@ -15,6 +15,7 @@ OE/Yocto Project, the Linux microPlatform™ and Docker®. getting-started/flash-device/index getting-started/register-device/index getting-started/install-fioctl/index + getting-started/emulation-with-qemu/index getting-started/building-deploying-app/index .. toctree:: diff --git a/source/reference-manual/qemu/qemu.rst b/source/reference-manual/qemu/qemu.rst index e79a81a9f..a60bafc3b 100644 --- a/source/reference-manual/qemu/qemu.rst +++ b/source/reference-manual/qemu/qemu.rst @@ -11,3 +11,6 @@ Qemu arm64 riscv64 +.. note:: + + If you are just getting started and prefer to emulate the device rather than using a physical board, make sure to refer to the guide :ref:`gs-emulation-with-qemu`. Following this guide will lead you through the same result of :ref:`gs-flash-device`, enabling you to proceed with the subsequent steps to :ref:`gs-register`.