Commit 48faa0883a for qemu.org
commit 48faa0883a53a962433b003ef3c7197f5490f201
Author: Brian Cain <brian.cain@oss.qualcomm.com>
Date: Mon Nov 9 12:30:17 2026 -0800
docs/system/hexagon: describe integrated firmware OS boot paths
Show how to boot a Linux guest with the hexagon_loadlinux firmware, and
hexagon_booter for running h2 user programs.
Reviewed-by: Pierrick Bouvier <pierrick.bouvier@oss.qualcomm.com>
Signed-off-by: Brian Cain <brian.cain@oss.qualcomm.com>
diff --git a/docs/system/hexagon/boot.rst b/docs/system/hexagon/boot.rst
index 36c603c69e..80eaac99c7 100644
--- a/docs/system/hexagon/boot.rst
+++ b/docs/system/hexagon/boot.rst
@@ -41,8 +41,8 @@ The virt machine
starts executing there.
``-bios`` with ``-kernel`` boots the kernel through Hexagon VM host
-firmware, as described in :ref:`hexagon-vm-boot`. The kernel window starts
-at ``0xa0000000``.
+firmware, as described in :ref:`hexagon-vm-boot`. Both ELF images load at
+their declared physical addresses.
Otherwise, guest software reads the generated DTB at ``0x99800000``.
``-append`` sets its ``/chosen/bootargs`` property.
@@ -80,13 +80,13 @@ Booting a kernel through Hexagon VM host firmware
On the ``virt`` and board-specific machines, ``-bios`` with ``-kernel``
starts the kernel through Hexagon VM host firmware. QEMU loads the firmware
-ELF as linked and adds the machine's kernel base to the kernel ELF's
-physical load addresses, so the kernel's addresses are relative to the
-start of its window. The kernel must use the corresponding Hexagon VM
-guest layout. QEMU starts thread zero at a boot stub at ``0x99c00000``.
-The stub passes the DTB address with the low word in ``r0`` and the high
-word in ``r1``, then jumps to the firmware's ELF entry point. The Hexagon
-VM host defines the child VM's register and execution state.
+ELF as linked. On ``virt``, it also loads the kernel ELF as linked. The
+board-specific machines add their configured kernel base to the kernel ELF's
+physical load addresses, so those kernels are relative to the start of the
+board's guest window. QEMU starts thread zero at a boot stub at
+``0x99c00000``. The stub passes the DTB address with the low word in ``r0``
+and the high word in ``r1``, then jumps to the firmware's ELF entry point.
+The Hexagon VM host defines the child VM's register and execution state.
QEMU places the DTB after the loaded kernel. QEMU copies it to guest RAM
before entering the firmware. An optional ``-initrd`` is placed
diff --git a/docs/system/hexagon/operating-systems.rst b/docs/system/hexagon/operating-systems.rst
new file mode 100644
index 0000000000..c64af28e1f
--- /dev/null
+++ b/docs/system/hexagon/operating-systems.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Booting guest operating systems
+===============================
+
+Hexagon VM guests require a Hexagon VM host. QEMU ships board-specific
+host firmware in ``pc-bios``. Guest operating systems boot with the
+``hexagon_loadlinux_*`` images; the ``hexagon_booter_*`` images run H2
+user programs instead (see :doc:`cdsp`). Select a matching machine,
+firmware, and guest memory layout from :doc:`cdsp`.
+
+Linux
+-----
+
+The kernel must be built for the Hexagon VM interface and include the
+PL011 console and required virtio-mmio device drivers.
+
+For a preloaded kernel and separate initramfs:
+
+.. code-block:: sh
+
+ qemu-system-hexagon -M qcs6490-cdsp -display none -serial stdio \
+ -bios hexagon_loadlinux_qcs6490_cdsp \
+ -kernel ./vmlinux -initrd ./initramfs.cpio.gz \
+ -append "console=ttyAMA0 rdinit=/init"
+
+``ttyAMA0`` selects the PL011 console. ``-append`` sets the boot arguments
+in QEMU's DTB; the guest and its VM host determine how those arguments
+are consumed. Add any platform-specific memory or delay-calibration
+parameters required by the kernel image.
+
+Guest operating systems on virt
+--------------------------------
+
+The ``virt`` machine boots a guest operating system through the same
+firmware:
+
+.. code-block:: sh
+
+ qemu-system-hexagon -M virt -display none -serial stdio \
+ -bios hexagon_loadlinux_sa8775p_cdsp \
+ -kernel ./guest.elf -append "console=ttyAMA0"
+
+QEMU loads the guest ELF at its declared physical addresses. QEMU enters
+the firmware with the DTB address in ``r1:r0`` (see
+:ref:`hexagon-vm-boot`). The guest must use the Hexagon VM interface for
+interrupts and timers, the PL011 at ``0x10000000``, and the virtio-mmio
+transports listed in :doc:`machines`.
diff --git a/docs/system/target-hexagon.rst b/docs/system/target-hexagon.rst
index dac8b9b348..3b63a94eb5 100644
--- a/docs/system/target-hexagon.rst
+++ b/docs/system/target-hexagon.rst
@@ -105,11 +105,23 @@ guest software can access the host console and filesystem. Read the
for details. Semihosting is enabled by default on hexagon-sim-compatible
machines. This can be further configured through ``-semihosting-config``.
+Hexagon VM host
+---------------
+
+Guest operating systems can run under a Hexagon VM host, which provides
+virtual processor, memory management, interrupt, and timer services.
+The `Hexagon Virtual Machine Specification
+<https://docs.qualcomm.com/doc/80-NB419-3/80-NB419-3_REV_A_Hexagin_Virtual_Machine_Specification.pdf>`__
+describes the guest interface. The OS boot examples in
+:doc:`hexagon/operating-systems` use H2 as the Hexagon VM host; QEMU
+emulates the underlying DSP hardware.
+
.. toctree::
:caption: Hexagon documentation
hexagon/machines
hexagon/sdk-programs
hexagon/boot
+ hexagon/operating-systems
hexagon/emulation
hexagon/cdsp