Add documentation regarding how QEMU handles Debug versions 0.13 and
1.0.

Signed-off-by: Daniel Henrique Barboza <daniel.barboza@oss.qualcomm.com>
---
 docs/specs/index.rst       |  1 +
 docs/specs/riscv-debug.rst | 68 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 69 insertions(+)
 create mode 100644 docs/specs/riscv-debug.rst

diff --git a/docs/specs/index.rst b/docs/specs/index.rst
index b7909a108a..181773515d 100644
--- a/docs/specs/index.rst
+++ b/docs/specs/index.rst
@@ -38,5 +38,6 @@ guest hardware that is specific to QEMU.
    rocker
    riscv-iommu
    riscv-aia
+   riscv-debug
    aspeed-intc
    iommu-testdev
diff --git a/docs/specs/riscv-debug.rst b/docs/specs/riscv-debug.rst
new file mode 100644
index 0000000000..e6dcad7d38
--- /dev/null
+++ b/docs/specs/riscv-debug.rst
@@ -0,0 +1,68 @@
+.. SPDX-License-Identifier: GPL-2.0-or-later
+
+.. _riscv-debug:
+
+RISC-V Debug support for RISC-V CPUs
+====================================
+
+Up until QEMU version 11.1 RISC-V CPUs historically supports Debug version
+0.13 via a "debug" flag that is enabled by default in the default rv64
+CPU.
+
+Starting on QEMU 11.2, RISC-V CPUs supports also Debug version 1.0, enabled
+via the "sdtrig" flag like a regular extension.  The default setting for rv64
+is still Debug 0.13 (debug = on, sdtrig = off),
+
+The "sdtrig" flag precedes "debug", i.e. if both are enabled the CPU will
+implement Debug 1.0.  In short:
+
+.. list-table:: "debug" and "sdtrig" flags and enabled Debug version
+   :widths: 25 25 25
+   :header-rows: 1
+
+   * - debug
+     - sdtrig
+     - Enabled Debug version
+   * - on
+     - off
+     - 0.13
+   * - on
+     - on
+     - 1.0
+   * - off
+     - on
+     - 1.0
+   * - off
+     - off
+     - All Debug versions disabled
+
+
+Debug 0.13 to 1.0 code/design changes
+-------------------------------------
+
+The effort done in QEMU version 11.2 to support Debug versions 0.13 and
+1.0 together was based in section 1.2.1.2 "Incompatible Changes from 0.13
+to 1.0" from the ratified `1.0 spec`_.  Here's how the proposed changes in
+that section were implemented in QEMU 11.2:
+
+Changes that aren't applicable due to either being SBI related or not present/supported in QEMU:
+    * "Make haltsum0 optional if there is only one hart."
+    * "System bus autoincrement only happens if an access actually takes place (sbdata0)."
+    * "Require debugger to poll dmactive after lowering it."
+
+Already implemented in the legacy Debug 0.13 base code:
+    * "When a selected trigger is disabled, tdata2 and tdata3 can be written with any value supported by any of the types this trigger supports."
+    * "tcontrol fields only apply to breakpoint traps, not any trap."
+
+All "hitN" fields are hardwired 0 thus no changes made:
+    * "If version is greater than 0, then hit0 (previously called mcontrol6.hit) now contains 0 when a trigger fires more than one instruction after the instruction that matched. (This information is now reflected in hit1.)"
+
+QEMU doesn't support encoding sizes greater than 64 bit so no change made:
+    * "If version is greater than 0, then the encodings of size for sizes greater than 64 bit have changed."
+
+Changes made in the 0.13 codebase to support Debug 1.0:
+    * "Add pending to icount."
+    * "If version is greater than 0, then bit 20 of mcontrol6 is no longer used for timing information. (Previously the bit was called mcontrol6.timing.)"
+
+
+.. _1.0 spec: https://docs.riscv.org/reference/debug/v1.0/_attachments/riscv-debug-specification.pdf
-- 
2.43.0

On Wed, 2026-08-05 at 15:25 -0300, Daniel Henrique Barboza wrote:
> Add documentation regarding how QEMU handles Debug versions 0.13 and
> 1.0.
> 
> Signed-off-by: Daniel Henrique Barboza
> <daniel.barboza@oss.qualcomm.com>

Reviewed-by: Alistair Francis <alistair.francis@wdc.com>

Alistair

> ---
>  docs/specs/index.rst       |  1 +
>  docs/specs/riscv-debug.rst | 68
> ++++++++++++++++++++++++++++++++++++++
>  2 files changed, 69 insertions(+)
>  create mode 100644 docs/specs/riscv-debug.rst
> 
> diff --git a/docs/specs/index.rst b/docs/specs/index.rst
> index b7909a108a..181773515d 100644
> --- a/docs/specs/index.rst
> +++ b/docs/specs/index.rst
> @@ -38,5 +38,6 @@ guest hardware that is specific to QEMU.
>     rocker
>     riscv-iommu
>     riscv-aia
> +   riscv-debug
>     aspeed-intc
>     iommu-testdev
> diff --git a/docs/specs/riscv-debug.rst b/docs/specs/riscv-debug.rst
> new file mode 100644
> index 0000000000..e6dcad7d38
> --- /dev/null
> +++ b/docs/specs/riscv-debug.rst
> @@ -0,0 +1,68 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +.. _riscv-debug:
> +
> +RISC-V Debug support for RISC-V CPUs
> +====================================
> +
> +Up until QEMU version 11.1 RISC-V CPUs historically supports Debug
> version
> +0.13 via a "debug" flag that is enabled by default in the default
> rv64
> +CPU.
> +
> +Starting on QEMU 11.2, RISC-V CPUs supports also Debug version 1.0,
> enabled
> +via the "sdtrig" flag like a regular extension.  The default setting
> for rv64
> +is still Debug 0.13 (debug = on, sdtrig = off),
> +
> +The "sdtrig" flag precedes "debug", i.e. if both are enabled the CPU
> will
> +implement Debug 1.0.  In short:
> +
> +.. list-table:: "debug" and "sdtrig" flags and enabled Debug version
> +   :widths: 25 25 25
> +   :header-rows: 1
> +
> +   * - debug
> +     - sdtrig
> +     - Enabled Debug version
> +   * - on
> +     - off
> +     - 0.13
> +   * - on
> +     - on
> +     - 1.0
> +   * - off
> +     - on
> +     - 1.0
> +   * - off
> +     - off
> +     - All Debug versions disabled
> +
> +
> +Debug 0.13 to 1.0 code/design changes
> +-------------------------------------
> +
> +The effort done in QEMU version 11.2 to support Debug versions 0.13
> and
> +1.0 together was based in section 1.2.1.2 "Incompatible Changes from
> 0.13
> +to 1.0" from the ratified `1.0 spec`_.  Here's how the proposed
> changes in
> +that section were implemented in QEMU 11.2:
> +
> +Changes that aren't applicable due to either being SBI related or
> not present/supported in QEMU:
> +    * "Make haltsum0 optional if there is only one hart."
> +    * "System bus autoincrement only happens if an access actually
> takes place (sbdata0)."
> +    * "Require debugger to poll dmactive after lowering it."
> +
> +Already implemented in the legacy Debug 0.13 base code:
> +    * "When a selected trigger is disabled, tdata2 and tdata3 can be
> written with any value supported by any of the types this trigger
> supports."
> +    * "tcontrol fields only apply to breakpoint traps, not any
> trap."
> +
> +All "hitN" fields are hardwired 0 thus no changes made:
> +    * "If version is greater than 0, then hit0 (previously called
> mcontrol6.hit) now contains 0 when a trigger fires more than one
> instruction after the instruction that matched. (This information is
> now reflected in hit1.)"
> +
> +QEMU doesn't support encoding sizes greater than 64 bit so no change
> made:
> +    * "If version is greater than 0, then the encodings of size for
> sizes greater than 64 bit have changed."
> +
> +Changes made in the 0.13 codebase to support Debug 1.0:
> +    * "Add pending to icount."
> +    * "If version is greater than 0, then bit 20 of mcontrol6 is no
> longer used for timing information. (Previously the bit was called
> mcontrol6.timing.)"
> +
> +
> +.. _1.0 spec:
> https://docs.riscv.org/reference/debug/v1.0/_attachments/riscv-debug-specification.pdf