docs: Add hexagon sysemu docs
Reviewed-by: Taylor Simpson <ltaylorsimpson@gmail.com> Signed-off-by: Brian Cain <brian.cain@oss.qualcomm.com>
Brian Cain committed
Jun 22, 2026 at 15:27 UTC
066bc54e064060b63e28a543f8e29c9961778e2b
6 files changed
+230
MAINTAINERS
+3
@@ -258,6 +258,9 @@ F: disas/hexagon.c
258
F: configs/targets/hexagon-linux-user.mak
259
F: tests/docker/dockerfiles/debian-hexagon-cross.docker
260
F: gdbstub/gdb-xml/hexagon*.xml
261
+F: docs/system/target-hexagon.rst
262
+F: docs/system/hexagon/
263
+F: docs/devel/hexagon-sys.rst
264
T: git https://github.com/qualcomm/qemu.git hex-next
265
266
Hexagon idef-parser
docs/devel/hexagon-sys.rst
new
+112
@@ -0,0 +1,112 @@
1
+.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+.. _Hexagon-System-arch:
4
+
5
+Hexagon System Architecture
6
+===========================
7
+
8
+The hexagon architecture has some unique elements which are described here.
9
+
10
+Interrupts
11
+----------
12
+When interrupts arrive at a Hexagon DSP core, they are priority-steered to
13
+be handled by an eligible hardware thread with the lowest priority.
14
+
15
+Memory
16
+------
17
+Each hardware thread has an ``SSR.ASID`` field that contains its Address
18
+Space Identifier. This value is catenated with a 32-bit virtual address -
19
+the MMU can then resolve this extended virtual address to a physical address.
20
+
21
+TLBs
22
+----
23
+The format of a TLB entry is shown below.
24
+
25
+.. note::
26
+ The Small Core DSPs have a different TLB format which is not yet
27
+ supported.
28
+
29
+.. admonition:: Diagram
30
+
31
+ .. code:: text
32
+
33
+ 6 5 4 3
34
+ 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
35
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
36
+ |v|g|x|A|A| | |
37
+ |a|l|P|1|0| ASID | Virtual Page |
38
+ |l|b| | | | | |
39
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
40
+
41
+ 3 2 1 0
42
+ 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
43
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
44
+ | | | | | | | |
45
+ |x|w|r|u|Cacheab| Physical Page |S|
46
+ | | | | | | | |
47
+ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
48
+
49
+
50
+* ASID: the address-space identifier
51
+* A1, A0: the behavior of these cache line attributes are not modeled by QEMU.
52
+* xP: the extra-physical bit is the most significant physical address bit.
53
+* S: the S bit and the LSBs of the physical page indicate the page size
54
+* val: this is the 'valid' bit, when set it indicates that page matching
55
+ should consider this entry.
56
+
57
+.. list-table:: Page sizes
58
+ :widths: 25 25 50
59
+ :header-rows: 1
60
+
61
+ * - S-bit
62
+ - Phys page LSBs
63
+ - Page size
64
+ * - 1
65
+ - N/A
66
+ - 4kb
67
+ * - 0
68
+ - 0b1
69
+ - 16kb
70
+ * - 0
71
+ - 0b10
72
+ - 64kb
73
+ * - 0
74
+ - 0b100
75
+ - 256kb
76
+ * - 0
77
+ - 0b1000
78
+ - 1MB
79
+ * - 0
80
+ - 0b10000
81
+ - 4MB
82
+ * - 0
83
+ - 0b100000
84
+ - 16MB
85
+
86
+* glb: if the global bit is set, the ASID is not considered when matching
87
+ TLBs.
88
+* Cacheab: the cacheability attributes of TLBs are not modeled, these bits
89
+ are ignored.
90
+* RWX: read-, write-, execute-, enable bits. Indicates if user programs
91
+ are permitted to read/write/execute the given page.
92
+* U: indicates if user programs can access this page.
93
+
94
+Scheduler
95
+---------
96
+The Hexagon system architecture has a feature to assist the guest OS
97
+task scheduler. The guest OS can enable this feature by setting
98
+``SCHEDCFG.EN``. The ``BESTWAIT`` register is programmed by the guest OS
99
+to indicate the priority of the highest priority task waiting to run on a
100
+hardware thread. The reschedule interrupt is triggered when any hardware
101
+thread's priority in ``STID.PRIO`` is worse than the ``BESTWAIT``. When
102
+it is triggered, the ``BESTWAIT.PRIO`` value is reset to 0x1ff.
103
+
104
+HVX Coprocessor
105
+---------------
106
+The Supervisor Status Register field ``SSR.XA`` binds a DSP hardware thread
107
+to one of the eight possible HVX contexts. The guest OS is responsible for
108
+managing this resource.
109
+
110
+.. seealso::
111
+
112
+ ``target/hexagon/README`` in the QEMU source tree for more info about Hexagon.
docs/devel/index-internals.rst
+1
@@ -14,6 +14,7 @@ Details about QEMU's various subsystems including how to add features to them.
14
block-coroutine-wrapper
15
clocks
16
ebpf_rss
17
+ hexagon-sys
18
migration/index
19
multi-process
20
reset
docs/system/hexagon/cdsp.rst
new
+12
@@ -0,0 +1,12 @@
1
+.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+Compute DSP
4
+===========
5
+
6
+A Hexagon CDSP is designed as a computation offload device for an SoC. The
7
+``V66G_1024`` machine contains:
8
+
9
+* L2VIC interrupt controller
10
+* QTimer timer device
11
+
12
+This machine will support any Hexagon CPU, but will default to ``v66``.
docs/system/target-hexagon.rst
new
+101
@@ -0,0 +1,101 @@
1
+.. SPDX-License-Identifier: GPL-2.0-or-later
2
+
3
+.. _Hexagon-System-emulator:
4
+
5
+Hexagon System emulator
6
+-----------------------
7
+
8
+Use the ``qemu-system-hexagon`` executable to simulate a 32-bit Hexagon
9
+machine.
10
+
11
+Hexagon Machines
12
+================
13
+
14
+Hexagon DSPs are suited to various functions and generally appear in a
15
+"DSP subsystem" of a larger system-on-chip (SoC).
16
+
17
+Hexagon DSPs are often included in a subsystem that looks like the diagram
18
+below. Instructions are loaded into DDR before the DSP is brought out of
19
+reset and the first instructions are fetched from DDR via the EVB/reset vector.
20
+
21
+In a real system, a TBU/SMMU would normally arbitrate AXI accesses but
22
+we don't have a need to model that for QEMU.
23
+
24
+Hexagon DSP cores use simultaneous multithreading (SMT) with as many as 8
25
+hardware threads.
26
+
27
+.. admonition:: Diagram
28
+
29
+ .. code:: text
30
+
31
+ AHB (local) bus AXI (global) bus
32
+ │ │
33
+ │ │
34
+ ┌─────────┐ │ ┌─────────────────┐ │
35
+ │ L2VIC ├──┤ │ │ │
36
+ │ ├──┼───────► ├───────┤
37
+ └─────▲───┘ │ │ Hexagon DSP │ │
38
+ │ │ │ │ │ ┌─────┐
39
+ │ │ │ N threads │ │ │ DDR │
40
+ │ ├───────┤ │ │ │ │
41
+ ┌────┴──┐ │ │ │ ├────────┤ │
42
+ │QTimer ├───┤ │ │ │ │ │
43
+ │ │ │ │ │ │ │ │
44
+ └───────┘ │ │ ┌─────────┐ │ │ │ │
45
+ │ │ ┌─────────┐│ │ │ │ │
46
+ ┌───────┐ │ │ │ HVX xM ││ │ │ │ │
47
+ │QDSP6SS├───┤ │ │ │┘ │ │ │ │
48
+ └───────┘ │ │ └─────────┘ │ │ └─────┘
49
+ │ │ │ │
50
+ ┌───────┐ │ └─────────────────┘ │
51
+ │ CSR ├───┤
52
+ └───────┘ │ ┌──────┐ ┌───────────┐
53
+ │ │ TCM │ │ VTCM │
54
+ │ │ │ │
55
+ └──────┘ │ │
56
+ │ │
57
+ │ │
58
+ │ │
59
+ └───────────┘
60
+
61
+Components
62
+----------
63
+Other than l2vic and HVX, the components below are not implemented in QEMU.
64
+
65
+* L2VIC: the L2 vectored interrupt controller. Supports 1024 input
66
+ interrupts, edge- or level-triggered. The core ISA has system registers
67
+ ``VID``, ``VID1`` which read through to the L2VIC device.
68
+* QTimer: ARMSSE-based programmable timer device. Its interrupts are
69
+ wired to the L2VIC. System registers ``TIMER``, ``UTIMER`` read
70
+ through to the QTimer device.
71
+* QDSP6SS: DSP subsystem features, accessible to the entire SoC, including
72
+ DSP NMI, watchdog, reset, etc.
73
+* CSR: Configuration/Status Registers.
74
+* TCM: DSP-exclusive tightly-coupled memory. This memory can be used for
75
+ DSPs when isolated from DDR and in some bootstrapping modes.
76
+* VTCM: DSP-exclusive vector tightly-coupled memory. This memory is accessed
77
+ by some HVX instructions.
78
+* HVX: the vector coprocessor supports 64 and 128-byte vector registers.
79
+ 64-byte mode is not implemented in QEMU.
80
+
81
+
82
+Bootstrapping
83
+-------------
84
+Hexagon systems do not generally have access to a block device. So, for
85
+QEMU the typical use case involves loading a binary or ELF file into memory
86
+and executing from the indicated start address::
87
+
88
+ $ qemu-system-hexagon -kernel ./prog -append 'arg1 arg2'
89
+
90
+Semihosting
91
+-----------
92
+Hexagon supports a semihosting interface similar to other architectures'.
93
+The ``trap0`` instruction can activate these semihosting calls so that the
94
+guest software can access the host console and filesystem. Semihosting
95
+is not yet implemented in QEMU hexagon.
96
+
97
+
98
+Hexagon Features
99
+================
100
+.. toctree::
101
+ hexagon/cdsp
docs/system/targets.rst
+1
@@ -30,3 +30,4 @@ Contents:
30
target-sparc64
31
target-i386
32
target-xtensa
33
+ target-hexagon