From dff3c4ec0111fd2f9fc3b67b3ac52d7132155605 Mon Sep 17 00:00:00 2001
From: Jan Matyas <jan.matyas@codasip.com>
Date: Wed, 16 Aug 2023 10:58:32 +0200
Subject: [PATCH] Program Buffer: Clarify requirements for case progbufsize==1

- Clarified that both the listed requirements apply only to
the case of progbufsize==1, as discussed in
https://github.com/riscv/riscv-debug-spec/issues/863

- Minor reword and simplification of the sentences

- Changed the order of paragraphs so that:
  - Generic requirements are stated first (Debug Mode, cmderr, ...)
  - Special requirements for progbufsize==1 are mentioned later
---
 debug_module.tex | 31 +++++++++++++++++--------------
 1 file changed, 17 insertions(+), 14 deletions(-)

diff --git a/debug_module.tex b/debug_module.tex
index b13f68ce..7767b1c9 100644
--- a/debug_module.tex
+++ b/debug_module.tex
@@ -463,20 +463,6 @@ \section{Program Buffer} \label{programbuffer}
 Program Buffer. This is indicated by \FdmDmstatusImpebreak. With this feature, a Program
 Buffer of just 2 32-bit words can offer efficient debugging.
 
-If \FdmAbstractcsProgbufsize is 1, \FdmDmstatusImpebreak must be 1. It is possible that the Program
-Buffer can hold only one 32- or 16-bit instruction, so the debugger must only
-write a single instruction in this case, regardless of its size.
-This instruction can be a 32-bit
-instruction, or a compressed instruction in the lower 16 bits accompanied by a
-compressed {\tt nop} in the upper 16 bits.
-
-\begin{commentary}
-    The slightly inconsistent behavior with a Program Buffer of size 1 is to
-    accommodate hardware designs that prefer to stuff instructions directly
-    into the pipeline when halted, instead of having the Program Buffer exist
-    in the address space somewhere.
-\end{commentary}
-
 While these programs are executed, the hart does not leave Debug Mode (see
 Section~\ref{debugmode}).  If an exception is encountered during execution of
 the Program Buffer, no more instructions are executed, the hart remains in Debug
@@ -484,6 +470,23 @@ \section{Program Buffer} \label{programbuffer}
 executes a program that doesn't terminate with an {\tt ebreak} instruction, the
 hart will remain in Debug Mode and the debugger will lose control of the hart.
 
+If \FdmAbstractcsProgbufsize is 1 then the following apply:
+
+\begin{enumerate}[nosep]
+    \item \FdmDmstatusImpebreak must be 1. 
+    \item The debugger must only write a single instruction into the Program Buffer,
+        regardless of the instruction size. It can be a 32-bit instruction, or 
+        a compressed instruction in the lower 16 bits accompanied by a compressed
+        {\tt nop} in the upper 16 bits.
+\end{enumerate}
+
+\begin{commentary}
+    This requirement on the debugger for the case of \FdmAbstractcsProgbufsize equal to 1 
+    is to accommodate hardware designs that prefer to stuff instructions directly into 
+    the pipeline when halted, instead of having the Program Buffer exist in the address 
+    space somewhere.
+\end{commentary}
+
 The Program Buffer may be implemented as RAM which is accessible to the
 hart. A debugger can determine if this is the case by executing small
 programs that attempt to write and read back relative to \Rpc while executing