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..621951198 --- /dev/null +++ b/source/getting-started/emulation-with-qemu/index.rst @@ -0,0 +1,120 @@ +.. _gs-emulation-with-qemu: + +Emulation With 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 machine to establish an environment for experimenting with FoundriesFactory®. + 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 ``QEMU Arm 64 bit`` platform 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 us 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. \ No newline at end of file diff --git a/source/getting-started/flash-device/index.rst b/source/getting-started/flash-device/index.rst index aca4f4fae..cb6358e84 100644 --- a/source/getting-started/flash-device/index.rst +++ b/source/getting-started/flash-device/index.rst @@ -21,6 +21,11 @@ Prerequisites and Pre-Work - Ethernet cable (if choosing Wired) - Console access to your hardware via UART serial (if choosing WiFi) +.. note:: + + If you're starting out and prefer emulation over a physical board, refer to the guide :ref:`gs-emulation-with-qemu`. + This guide will walk you through "Flashing the Image," allowing you to move on 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..bc6493f29 100644 --- a/source/reference-manual/qemu/qemu.rst +++ b/source/reference-manual/qemu/qemu.rst @@ -11,3 +11,9 @@ Qemu arm64 riscv64 +.. note:: + + If you're just starting and prefer emulation, refer to the guide :ref:`gs-emulation-with-qemu`. + This guide achieves the same result as :ref:`gs-flash-device`. + Afterward, you can proceed with the subsequent steps to :ref:`gs-register`. +