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
