Signed-off-by: Brian Cain <[email protected]>
---
 docs/system/hexagon/cdsp.rst     | 41 +++++++++++++++-----------------
 docs/system/hexagon/machines.rst | 38 +++++++++++++++++++++++++++++
 docs/system/target-hexagon.rst   |  5 ++--
 3 files changed, 60 insertions(+), 24 deletions(-)
 create mode 100644 docs/system/hexagon/machines.rst

diff --git a/docs/system/hexagon/cdsp.rst b/docs/system/hexagon/cdsp.rst
index 8d3a1f611b0..3556d8a8aa0 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 00000000000..a4760b7a5b1
--- /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 5d48cf401ad..5a646fd0d04 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
 
-- 
2.34.1

Reply via email to