[PATCH 5/5] docs/specs: add RISC-V CPU Debug support info

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

Signed-off-by: Daniel Henrique Barboza <[email protected]>
---
 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