Commit 13991a855a for qemu.org
commit 13991a855a85b0b4e4df90d592bcb66b4fa464b2
Author: Brian Cain <brian.cain@oss.qualcomm.com>
Date: Mon Nov 9 12:30:15 2026 -0800
docs/system/hexagon: document boot interfaces
Describe ELF and raw-image loading, reset state, the DTB handoff to VM
host firmware, and initial thread state. Explain UART and semihosting
console routing.
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
new file mode 100644
index 0000000000..36c603c69e
--- /dev/null
+++ b/docs/system/hexagon/boot.rst
@@ -0,0 +1,100 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Hexagon boot interface
+======================
+
+``qemu-system-hexagon`` loads the initial image. Guest startup code
+initializes the stack, exception handling, and runtime state. When a
+Hexagon VM host is loaded, it establishes the guest OS's boot environment.
+
+Initial hardware state
+----------------------
+
+Only hardware thread zero starts executing. Other threads start powered
+off.
+
+Execution uses untranslated physical addresses in monitor mode. Guest software
+must populate TLB entries before enabling the MMU, and set up exception vectors
+and interrupt masks before enabling interrupts. See
+:doc:`../../devel/hexagon-sys` for the system architecture.
+
+QEMU sets thread zero's PC to the selected image entry address. ``EVB``
+initially contains zero; ELF startup code installs its own aligned event
+vector base.
+
+Simulator-compatible machines
+-----------------------------
+
+``-kernel file`` loads a little-endian Hexagon ELF, places its loadable
+segments according to their physical addresses, zero-fills the segments'
+remaining memory, and starts thread zero at the ELF entry point. Link
+startup code for untranslated execution, with the entry point accessible
+at its linked address.
+
+The virt machine
+----------------
+
+``-kernel file`` alone loads a Hexagon ELF into DDR, which starts at
+``0x80000000``, and starts at its ELF entry point.
+
+``-bios file`` alone loads a raw firmware image at the start of DDR and
+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``.
+
+Otherwise, guest software reads the generated DTB at ``0x99800000``.
+``-append`` sets its ``/chosen/bootargs`` property.
+
+Board-specific machines
+------------------------------------
+
+Both ``-kernel`` and ``-bios`` accept Hexagon ELF images. The combinations
+have different meanings:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Options
+ - Loading and entry
+ * - ``-kernel`` alone
+ - Load segments at ELF physical addresses and start at the ELF entry.
+ * - ``-bios`` alone
+ - Load firmware segments at ELF physical addresses and start at its entry.
+ * - ``-bios`` and ``-kernel``
+ - Load firmware normally, relocate the kernel segments into the board's
+ kernel window, and enter firmware through a QEMU boot stub.
+
+The combined case is described in :ref:`hexagon-vm-boot`, using the kernel
+base in :doc:`cdsp`.
+
+``-dtb file`` replaces the generated tree. A nonempty ``-append`` value
+sets its ``/chosen/bootargs``. A replacement tree must describe the
+selected hardware-thread count, actual RAM, and matching device drivers.
+
+.. _hexagon-vm-boot:
+
+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.
+
+QEMU places the DTB after the loaded kernel. QEMU copies it to guest RAM
+before entering the firmware. An optional ``-initrd`` is placed
+after the DTB base. ``-initrd`` requires both ``-bios`` and ``-kernel``.
+
+Console and semihosting
+-----------------------
+
+SDK simulator programs use semihosting for console I/O. The ``virt`` and
+board-specific machines also provide a PL011 UART, whose host backend is
+selected with ``-serial``.
diff --git a/docs/system/target-hexagon.rst b/docs/system/target-hexagon.rst
index 7b7d0bc31b..e091b75c7a 100644
--- a/docs/system/target-hexagon.rst
+++ b/docs/system/target-hexagon.rst
@@ -107,5 +107,6 @@ machines. This can be further configured through ``-semihosting-config``.
:caption: Hexagon documentation
hexagon/machines
+ hexagon/boot
hexagon/emulation
hexagon/cdsp