Commit 70ff19cb8c for qemu.org

commit 70ff19cb8c818caadcabed3fa424e1478c7a2a35
Author: Brian Cain <brian.cain@oss.qualcomm.com>
Date:   Mon Nov 9 12:30:13 2026 -0800

    docs/system/hexagon: describe machine models and memory maps

    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/cdsp.rst b/docs/system/hexagon/cdsp.rst
index 8d3a1f611b..3556d8a8aa 100644
--- a/docs/system/hexagon/cdsp.rst
+++ b/docs/system/hexagon/cdsp.rst
@@ -1,21 +1,12 @@
 .. SPDX-License-Identifier: GPL-2.0-or-later

-Compute DSP
-===========
+Board-specific boot firmware
+============================

-A Hexagon CDSP is designed as a computation offload device for an SoC.  The
-``V66G_1024`` machine contains:
-
-* L2VIC interrupt controller
-* QTimer timer device
-
-This machine will support any Hexagon CPU, but will default to ``v66``.
-
-H2 boot firmware
-----------------
-
-These machines can be started through the H2 hypervisor images shipped in
-``pc-bios``, selected with ``-bios``:
+The CDSP/NSP machines can use the host firmware shipped in ``pc-bios``,
+selected with ``-bios``. These images contain H2 and either the ``booter``
+or ``loadlinux`` loader. Use ``-L`` to specify QEMU's firmware directory
+when running an uninstalled build.

 .. list-table::
    :header-rows: 1
@@ -45,16 +36,22 @@ These machines can be started through the H2 hypervisor images shipped in
      - ``0xa0000000``
      - ``sa8797p_nsp0``

+``hexagon_loadlinux_<suffix>``
+  Boots a guest operating system written for the Hexagon VM interface.
+  Despite the name, it is not specific to Linux. H2 starts the guest from
+  an image that QEMU has placed at the ``-kernel`` address in the table
+  above.
+
 ``hexagon_booter_<suffix>``
-  H2 plus a loader that reads guest ELF files from the host through QEMU
-  semihosting::
+  Runs H2 user programs.  The booter creates a VM, loads a program
+  that it reads from the host through semihosting, and waits for the
+  program to exit::

     qemu-system-hexagon -M qcs6490-cdsp -serial stdio -display none \
         -bios hexagon_booter_qcs6490_cdsp \
-        -semihosting-config enable=on,target=native,arg=booter,arg=guest.elf
+        -semihosting-config enable=on,target=native,arg=booter,arg=prog.elf

-  Guests are loaded at ``0xa2000000``.
+  Programs are loaded at ``0xa2000000`` by default; the booter's
+  ``--guest_base`` option changes this (``arg=--help`` lists its options).

-``hexagon_loadlinux_<suffix>``
-  H2 plus a loader that starts a kernel which QEMU has placed at the
-  ``-kernel`` address in the table above.
+  For more info, see <https://github.com/qualcomm/hexagon-hypervisor>.
diff --git a/docs/system/hexagon/machines.rst b/docs/system/hexagon/machines.rst
new file mode 100644
index 0000000000..a4760b7a5b
--- /dev/null
+++ b/docs/system/hexagon/machines.rst
@@ -0,0 +1,38 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+Hexagon machines
+================
+
+Choose a machine that matches the runtime environment for the program and
+the Hexagon ISA it targets. Hexagon machines fall into two broad categories:
+simulator-compatible machines and board-specific DSP subsystem machines.
+
+Simulator-compatible machines
+-----------------------------
+
+Simulator-compatible machines support standalone SDK OS and QuRT programs
+intended for the Hexagon simulator environment. They provide the common
+Hexagon system facilities expected by those programs, including interrupt
+and timer services, local memory, semihosting, and a configuration table
+that describes the selected model's capabilities.
+
+Select the model that matches the program's target ISA and threading
+requirements. ``V66G_1024`` is the default when ``-M`` is omitted; ``sim``
+selects the most modern simulator-style machine.
+
+The virtual machine (``virt``)
+------------------------------
+
+``virt`` is a synthetic simulator-compatible board for operating systems and
+bare-metal programs. QEMU supplies a device tree that describes the virtual
+hardware available to the guest, including CPUs, interrupt controller,
+console, virtio devices, and accelerator capabilities. See :doc:`boot` for
+its boot protocol.
+
+Board-specific CDSP and NSP machines
+------------------------------------
+
+Board-specific CDSP and NSP machines model the DSP subsystem of a named
+SoC.
+
+Firmware choices are listed in :doc:`cdsp`.
diff --git a/docs/system/target-hexagon.rst b/docs/system/target-hexagon.rst
index 5d48cf401a..5a646fd0d0 100644
--- a/docs/system/target-hexagon.rst
+++ b/docs/system/target-hexagon.rst
@@ -21,8 +21,8 @@ reset and the first instructions are fetched from DDR via the EVB/reset vector.
 In a real system, a TBU/SMMU would normally arbitrate AXI accesses but
 we don't have a need to model that for QEMU.

-Hexagon DSP cores use simultaneous multithreading (SMT) with as many as 8
-hardware threads.
+Hexagon DSP cores use simultaneous multithreading (SMT). The number of
+hardware threads depends on the machine.

 .. admonition:: Diagram

@@ -100,6 +100,7 @@ machines. This can be further configured through ``-semihosting-config``.
 Hexagon Features
 ================
 .. toctree::
+   hexagon/machines
    hexagon/emulation
    hexagon/cdsp