Show how to boot a Linux guest with the hexagon_loadlinux firmware, and
hexagon_booter for running h2 user programs.

Signed-off-by: Brian Cain <[email protected]>
---
 docs/system/hexagon/operating-systems.rst | 50 +++++++++++++++++++++++
 docs/system/target-hexagon.rst            | 12 ++++++
 2 files changed, 62 insertions(+)
 create mode 100644 docs/system/hexagon/operating-systems.rst

diff --git a/docs/system/hexagon/operating-systems.rst 
b/docs/system/hexagon/operating-systems.rst
new file mode 100644
index 00000000000..f367fc6387f
--- /dev/null
+++ b/docs/system/hexagon/operating-systems.rst
@@ -0,0 +1,50 @@
+.. 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, using a ``hexagon_loadlinux_*`` image whose kernel address in
+:doc:`cdsp` is ``0xa0000000``:
+
+.. code-block:: sh
+
+    qemu-system-hexagon -M virt -display none -serial stdio \
+        -bios hexagon_loadlinux_sa8775p_cdsp \
+        -kernel ./guest.elf -append "console=ttyAMA0"
+
+The guest ELF's physical load addresses are relative to the start of the
+kernel window at ``0xa0000000``, so a guest linked at physical address zero
+is loaded there. 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 dac8b9b3483..3b63a94eb56 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
-- 
2.34.1

Reply via email to