draft: hexagon system emulation initial

MAINTAINERS

@@ -237,6 +237,9 @@ F: disas/hexagon.c
 F: configs/targets/hexagon-linux-user/default.mak
 F: docker/dockerfiles/debian-hexagon-cross.docker
 F: gdb-xml/hexagon*.xml
+F: docs/system/target-hexagon.rst
+F: docs/devel/hexagon-sys.rst
+F: docs/devel/hexagon-vm.rst
 T: git https://github.com/quic/qemu.git hex-next
 
 Hexagon idef-parser

docs/devel/hexagon-sys.rst

@@ -0,0 +1,106 @@
+.. _Hexagon-System-arch:
+
+Hexagon System Architecture
+===========================
+
+The hexagon architecture has some unique elements which are described here.
+
+Interrupts
+----------
+When interrupts arrive at a Hexagon DSP core, they are priority-steered to
+be handled by an eligible hardware thread with the lowest priority.
+
+Memory
+------
+Each hardware thread has an ``SSR.ASID`` field that contains its Address
+Space Identifier.  This value is catenated with a 32-bit virtual address -
+the MMU can then resolve this extended virtual address to a physical address.
+
+TLBs
+----
+The format of a TLB entry is shown below.
+
+.. note::
+    The Small Core DSPs have a different TLB format which is not yet
+    supported.
+
+.. admonition:: Diagram
+
+ .. code:: text
+
+             6                   5                   4               3
+       3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      |v|g|x|A|A|             |                                       |
+      |a|l|P|1|0|     ASID    |             Virtual Page              |
+      |l|b| | | |             |                                       |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+         3                   2                   1                   0
+       1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+      | | | | |       |                                             | |
+      |x|w|r|u|Cacheab|               Physical Page                 |S|
+      | | | | |       |                                             | |
+      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+
+
+* ASID: the address-space identifier
+* A1, A0: the behavior of these cache line attributes are not modeled by QEMU.
+* xP: the extra-physical bit is the most significant physical address bit.
+* S: the S bit and the LSBs of the physical page indicate the page size
+* val: this is the 'valid' bit, when set it indicates that page matching
+  should consider this entry.
+
+.. list-table:: Page sizes
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - S-bit
+     - Phys page LSBs
+     - Page size
+   * - 1
+     - N/A
+     - 4kb
+   * - 0
+     - 0b1
+     - 16kb
+   * - 0
+     - 0b10
+     - 64kb
+   * - 0
+     - 0b100
+     - 256kb
+   * - 0
+     - 0b1000
+     - 1MB
+   * - 0
+     - 0b10000
+     - 4MB
+   * - 0
+     - 0b100000
+     - 16MB
+
+* glb: if the global bit is set, the ASID is not considered when matching
+  TLBs.
+* Cacheab: the cacheability attributes of TLBs are not modeled, these bits
+  are ignored.
+* RWX: read-, write-, execute-, enable bits.  Indicates if user programs
+  are permitted to read/write/execute the given page.
+* U: indicates if user programs can access this page.
+
+Scheduler
+---------
+The Hexagon system architecture has a feature to assist the guest OS
+task scheduler.  The guest OS can enable this feature by setting
+``SCHEDCFG.EN``.  The ``BESTWAIT`` register is programmed by the guest OS
+to indicate the priority of the highest priority task waiting to run on a
+hardware thread.  The reschedule interrupt is triggered when any hardware
+thread's priority in ``STID.PRIO`` is worse than the ``BESTWAIT``.  When
+it is triggered, the ``BESTWAIT.PRIO`` value is reset to 0x1ff.
+
+HVX Coprocessor
+---------------
+The Supervisor Status Register field ``SSR.XA`` binds a DSP hardware thread
+to one of the eight possible HVX contexts.  The guest OS is responsible for
+managing this resource.

docs/devel/hexagon-vm.rst

@@ -0,0 +1,190 @@
+Hexagon Virtual Machine
+=======================
+
+The hexagon virtual machine is a hypervisor that can partition a single
+Hexagon DSP among multiple guest operating systems, and abstracts the
+specific details of a DSP architectural revision for the sake of consistency
+among generations.
+
+Events
+------
+
+The guest operating system should register the Guest Event Vector Base
+via the ``vmsetvec`` virtual instruction at system startup.  The vector table
+and handlers are determined by the guest OS.
+
+Guests return from event handlers with ``vmrte``.  This instruction will restore
+the mode (user versus guest), interrupt enable state, PC, SP.
+
+.. list-table:: Event types
+   :header-rows: 1
+
+   * - Number
+     - Name
+     - Description
+     - Maskable
+     - Detail
+   * - 0
+     - Reserved
+     -
+     -
+     -
+   * - 1
+     - Machine check event
+     - unrecoverable VM state
+     - No
+     - execution terminates if unhandled
+   * - 2
+     - General exception
+     - internal hardware or software exception
+     - No
+     -
+   * - 3-4
+     - Reserved
+     -
+     -
+     -
+   * - 5
+     - ``trap0``
+     - ``trap0`` instruction
+     - No
+     -
+   * - 6
+     - Reserved
+     -
+     -
+     -
+   * - 7
+     - Interrupt
+     - external interrupts
+     - Yes
+     - increasing interrupt numbers have descending priority
+
+Startup
+-------
+In order to transition to user-mode, the guest OS must set the ``UM`` bit in
+the guest status register and specify the address to start executing in
+user mode in the guest event link register.
+
+Virtual Instructions
+--------------------
+
+.. list-table:: Virtual Instructions
+   :header-rows: 1
+
+   * - Instruction
+     - Behavior
+     - Operand
+     - Input
+     - Output
+   * - vmversion
+     - returns the VM version
+     - 0x0
+     - requested VM version
+     - provided VM version
+   * - vmrte
+     - return from event
+     - 0x1
+     - Event info in g3:0
+     - N/A
+   * - vmsetvec
+     - set event vector
+     - 0x2
+     - r0 is set to vector table addr
+     - r0 is 0 on success, 1 otherwise
+   * - vmsetie
+     - set interrupt enabled
+     - 0x3
+     - r0 is set to 1 to enable, 0 to disable
+     - previous IE bit is stored as LSB of r0
+   * - vmgetie
+     - get interrupt enabled
+     - 0x4
+     - N/A
+     - current IE bit is stored as LSB of r0
+   * - vmintop
+     - interrupt operation
+     - 0x5
+     - r0 = Interrupt Op, r1-r4: Depends on Op
+     - r0 - value depends on operation
+   * - vmclrmap
+     - clear virtual memory map
+     - 0xa
+     - r0 = Interrupt Op, r1-r4: Depends on Op
+     - r0 - value depends on operation
+   * - vmnewmap
+     - set new virtual memory map
+     - 0xb
+     - + r0 contains logical address of new segment table
+       + r1 = type of translations: 0 indicates a logical address of a zero-terminated linear list, 1 indicates a set of page tables.
+     - r0 contains 0 on success, otherwise negative error code
+   * - vmcache
+     - VM cache control: not modeled
+     - 0xd
+     - + r0 contains the operation to be performed
+       + r1 = Starting virtual address
+       + r2 contains the length in bytes
+     - r0 contains 0 on success, otherwise -1.  Cache behavior is not modeled so this operation always succeeds.
+   * - vmgettime
+     - Get virtual machine time
+     - 0xe
+     - N/A
+     - r0 contains the least significant 32 bits of timestamp, r1 contains the  most significant 32 bits of timestamp
+   * - vmsettime
+     - Set virtual machine time
+     - 0xf
+     - r0 contains the least significant 32 bits of timestamp, r1 contains the  most significant 32 bits of timestamp
+     - N/A
+   * - vmwait
+     - wait for interrupt
+     - 0x10
+     - N/A
+     - r0 contains the interrupt number of the interrupt waking the guest
+   * - vmyield
+     - voluntarily yield VM task
+     - 0x11
+     - N/A
+     - N/A
+   * - vmstart
+     - Create new virtual processor instance
+     - 0x12
+     - r0 contains the starting execution address, r1 contains the starting stack pointer
+     - r0 contains the Virtual processor number of new virtual processor on success, otherwise -1
+   * - vmstop
+     - terminate current virtual processor instance
+     - 0x13
+     - N/A
+     - N/A
+   * - vmvpid
+     - get the virtual processor ID
+     - 0x14
+     - N/A
+     - r0 contains the virtual processor number of virtual processor executing the instruction
+   * - vmsetregs
+     - Set guest registers
+     - 0x15
+     - r0-3 hold g0-3 values
+     - N/A
+   * - vmgetregs
+     - Get guest registers
+     - 0x16
+     - N/A
+     - r0-3 hold g0-3 values
+   * - vmtimerop
+     - perform an operation on a system timer
+     - 0x18
+     - + getfreq = 0
+       + getres = 1
+       + gettime = 2
+       + gettimeout = 3
+       + settimeout = 4
+       + deltatimeout = 5
+     - r0 contains result of the timer operation call
+   * - vmgetinfo
+     - Get system info
+     - 0x1a
+     - Index of the system info parameter:
+
+       + build_id = 0
+       + info_boot_flags = 1
+     - value of the indicated system info parameter

docs/devel/index-internals.rst

@@ -12,6 +12,8 @@ Details about QEMU's various subsystems including how to add features to them.
    block-coroutine-wrapper
    clocks
    ebpf_rss
+   hexagon-sys
+   hexagon-vm
    migration/index
    multi-process
    reset

docs/system/hexagon/cdsp.rst

@@ -0,0 +1,10 @@
+Compute DSP
+===========
+
+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``.

docs/system/hexagon/emulation.rst

@@ -0,0 +1,16 @@
+.. _Hexagon Emulation:
+
+Hexagon CPU architecture support
+================================
+
+QEMU's TCG emulation includes support for v65, v66, v67, v68, v69, v71, v73.
+It also has support for the following architecture extensions:
+
+- HVX (Hexagon Vector eXtensions)
+
+For information on the specifics of the HVX extension, please refer
+to the `Qualcomm Hexagon V69 HVX Programmer's Reference Manual
+<https://docs.qualcomm.com/bundle/publicresource/80-N2040-49_REV_AA_Qualcomm_Hexagon_V69_HVX_ProgrammerS_Reference_Manual.pdf>`_.
+
+.. code-block:: bash
+