Implement the Sdext debug mode extension.

The try_step API was changed to reflect the current debug mode
state and to provide a mechanism for the external harness to
request a change in that state (i.e. enter and exit debug mode).

Two new callbacks indicate entry and exit from debug mode.

This does not provide a model-external harness to connect to
external debugger infrastructure; that is left for the future.

Hook functions have been defined for behavior that is
UNSPECIFIED in the debug specification or depends on the
debugger's memory map (in riscv_sdext_hook_insts).

StopCount is implemented for the single-hart case, with a note
marking the change needed for multi-hart emulation.

Some notes have been added under doc/ about the sdext
implementation.

Author: pmundkur

c_emulator/riscv_callbacks.cpp

@@ -137,3 +137,13 @@ unit trap_callback(unit)
   }
   return UNIT;
 }
+
+unit debug_entry_callback(unit)
+{
+  return UNIT;
+}
+
+unit debug_exit_callback(unit)
+{
+  return UNIT;
+}

c_emulator/riscv_callbacks.h

@@ -23,6 +23,8 @@ unit csr_full_read_callback(const_sail_string csr_name, unsigned reg,
 unit vreg_write_callback(unsigned reg, lbits value);
 unit pc_write_callback(uint64_t value);
 unit trap_callback(unit);
+unit debug_entry_callback(unit);
+unit debug_exit_callback(unit);
 
 // TODO: Move these implementations to C.
 unit zrvfi_write(uint64_t paddr, int64_t width, lbits value);

c_emulator/riscv_sim.cpp

@@ -543,7 +543,7 @@ void flush_logs(void)
 
 void run_sail(void)
 {
-  bool is_waiting;
+  struct zstep_result step_result = {false, false, false, false};
   bool exit_wait = true;
   bool diverged = false;
 
@@ -578,7 +578,12 @@ void run_sail(void)
       sail_int sail_step;
       CREATE(sail_int)(&sail_step);
       CONVERT_OF(sail_int, mach_int)(&sail_step, step_no);
-      is_waiting = ztry_step(sail_step, exit_wait);
+
+      // If the model is in Debug mode, request an exit, else request
+      // no change.
+      enum zdebug_request dr
+          = step_result.zin_debug_mode ? zDR_Resume : zDR_None;
+      step_result = ztry_step(sail_step, exit_wait, dr);
       if (have_exception)
         goto step_exception;
       flush_logs();
@@ -587,7 +592,10 @@ void run_sail(void)
         rvfi->send_trace(config_print_rvfi);
       }
     }
-    if (!is_waiting) {
+    // TODO: better handling of entry into debug mode (step_result.zin_debug),
+    // e.g, by connecting to a debugger interface.
+    // For now, we just request an immediate resume above.
+    if (!step_result.zin_wait) {
       if (config_print_step) {
         fprintf(trace_log, "\n");
       }

config/default.json

@@ -225,6 +225,21 @@
     "Zvkt": {
       "supported": true
     },
+    "Sdext": {
+      "supported": true,
+      "mem_base": 0,
+      "mem_size": 1024,
+      "trap_vector": 0,
+      "writable_stepie": true,
+      "stopcount": {
+        "writable": true,
+        "preset_value": false
+      },
+      "mprven": {
+        "writable": true,
+        "preset_value": true
+      }
+    },
     "Sscofpmf": {
       "supported": true
     },

doc/figs/Makefile

@@ -1,4 +1,4 @@
-all: riscvspecdeps.svg riscvcsimdeps.svg
+all: riscvspecdeps.svg riscvcsimdeps.svg debug_mode_sm.svg
 
 %.pdf: %.tex
 	pdflatex $<
@@ -7,5 +7,6 @@ all: riscvspecdeps.svg riscvcsimdeps.svg
 	dvisvgm -Z 1.5 --pdf $<
 
 clean:
-	rm riscvspecdeps.pdf riscvspecdeps.aux riscvspecdeps.log
-	rm riscvcsimdeps.pdf riscvcsimdeps.aux riscvcsimdeps.log
+	rm -f riscvspecdeps.pdf riscvspecdeps.aux riscvspecdeps.log
+	rm -f riscvcsimdeps.pdf riscvcsimdeps.aux riscvcsimdeps.log
+	rm -f debug_mode_sm.pdf debug_mode_sm.aux debug_mode_sm.log

doc/figs/debug_mode_sm.svg

@@ -0,0 +1,71 @@
+\documentclass{standalone}
+\usepackage{tikz}
+\usetikzlibrary{calc,positioning,backgrounds}
+\begin{document}
+\begin{tikzpicture}[
+    % these two lines are needed for the svg to receive a white background.
+    background rectangle/.style={rounded corners,fill=white},
+    framed,
+    % general settings
+    node distance=6cm,
+    align=center,
+    % nodes
+    base/.style={rectangle, rounded corners=3mm, minimum size=10mm, thick, draw=black},
+    wait/.style={base, draw=black},
+    debug/.style={base, draw=black, fill=red!30},
+    % arrow labels
+    label/.style={text=black},
+    hltlabel/.style={text=red},
+    reslabel/.style={text=green},
+    % arrows
+    enterwait/.style={black, thick},
+    exitwait/.style={black, very thick},
+    halt/.style={red, thick},
+    resume/.style={green, thick},
+    dbgarr/.style={black, thick},
+  ]
+
+  \node (dbg)      [debug]                             {\textbf{Active}\\
+                                                        \textit{Debug Mode}};
+
+  \node (active)   [base, above left  of=dbg]          {\textbf{Active}};
+  \node (wait)     [wait, above right of=dbg]          {\textbf{Waiting}};
+
+  \node (dbg-cmd)  [debug, below of=dbg]               {\textbf{Active}\\
+                                                        \textit{Debug Mode}\\
+                                                        \textit{Abstract Command}};
+
+  % not used anymore.
+  %\node (dbg-err)  [debug, below right of=dbg]         {\textbf{Active}\\
+  %                                                      \textit{Debug Mode}\\
+  %                                                      \textit{Abstract Command Error}};
+
+  % control for enterwait arrow
+  \coordinate (nwaitloc) at ($(active)!0.5!(wait)+(0,0.5cm)$);
+  % control for exitwait arrow
+  \coordinate (xwaitloc) at ($(active)!0.5!(wait)-(0,0.5cm)$);
+
+  \draw[->,enterwait] (active) .. controls (nwaitloc) .. node[label,above]{\textbf{WFI,WRS}}      (wait);
+  \draw[->,exitwait]  (wait)   .. controls (xwaitloc) .. node[label,below]{\texttt{exit\_wait}}   (active);
+
+  % control for halt-active arrow
+  \coordinate (haltactloc) at ($(active)!0.5!(dbg)+(0.5cm,0.5cm)$);
+  % control for resume arrow
+  \coordinate (resumeloc) at ($(active)!0.5!(dbg)-(0.5cm,0.5cm)$);
+
+  \draw[->,halt]   (active)  .. controls (haltactloc) .. node[hltlabel,right]{\textbf{EBREAK}\\\texttt{DR\_halt}\\\texttt{dcsr.step}} (dbg);
+  \draw[->,halt]   (wait)    -- node[hltlabel,right]{\texttt{DR\_halt}}                                           (dbg);
+  \draw[->,resume] (dbg)     .. controls (resumeloc)  .. node[reslabel,left]{\texttt{DR\_resume}\\\textbf{DRET}}     (active);
+
+  % control for start-cmd arrow
+  \coordinate (startcmdloc) at ($(dbg)!0.5!(dbg-cmd)+(0.5cm,0)$);
+  % control for end-cmd arrow
+  \coordinate (endcmdloc)   at ($(dbg)!0.5!(dbg-cmd)-(0.5cm,0)$);
+
+  \draw[->,dbgarr] (dbg)     .. controls (startcmdloc) .. node[label,right, near end]{\texttt{start\_debug\_abstract\_command}} (dbg-cmd);
+  \draw[->,dbgarr] (dbg-cmd) .. controls (endcmdloc)   .. node[label,left, near end]{\textbf{EBREAK}\\(Exception error)}        (dbg);
+
+  \draw[->,resume] (dbg-cmd) edge [out=135,in=-135] node[reslabel,left]{\texttt{DR\_resume}}                                    (active);
+
+\end{tikzpicture}
+\end{document}

doc/figs/debug_mode_sm.tex

@@ -0,0 +1,35 @@
+This is a brief description of the hart states involved in the
+implementation of the `Sdext` extension.
+
+image::./figs/debug_mode_sm.svg[align="center"]
+
+Under normal (non-Debug mode) operation, the `hart_state` is either
+`Active` or `Waiting`.  The `Waiting` state is entered by the `WFI`
+and `WRS.{NTO,STO}` instructions, and exited due to reasons such as
+incoming interrupts or reservations becoming invalid.
+
+Debug Mode creates two additional states for the hart that are
+variants of the `Active` state.  The `Active (Debug Mode)` state is
+entered from the Active state either by executing an `EBREAK`, after
+executing an instruction in single-step mode (i.e. `dcsr[Step]` is
+set), or being requested to halt (`DR_halt`) by the external harness
+driving the model.  If the halt request is made when the hart is
+`Waiting`, the hart completes the execution of the waiting instruction
+and enters the `Active (Debug Mode)` state.
+
+When in `Active (Debug Mode)`, the debugger might request the
+execution of abstract commands (which may include the execution of
+instructions from a debug program buffer).  The hart enters the
+`Active (Debug Mode Abstract Command)` state to perform this
+execution.  This state is left either by executing an `EBREAK` or
+encountering an exception during execution; in both cases, the hart
+transitions back to `Active (Debug Mode)`.  An error condition is set
+in the latter exception case; this should be checked (and then
+cleared) by the external harness.
+
+The external harness can also request the model to exit the Debug mode
+states and re-enter `Active` with `DR_resume`.
+
+The `DR_halt` and `DR_resume` requests to the model are made using
+arguments to the `try_step()` function that serves as the primary
+interface between the model and external harness.

doc/notes_Debug_Mode.adoc

@@ -65,6 +65,7 @@ foreach (xlen IN ITEMS 32 64)
             )
 
             set(sail_default_inst
+                "riscv_sdext_inst_hooks.sail"
                 "riscv_insts_base.sail"
                 "riscv_insts_zifencei.sail"
                 "riscv_insts_zaamo.sail"
@@ -79,6 +80,7 @@ foreach (xlen IN ITEMS 32 64)
                 "riscv_insts_dext.sail"
                 "riscv_insts_zcd.sail"
                 "riscv_insts_svinval.sail"
+                "riscv_insts_sdext.sail"
                 "riscv_insts_zba.sail"
                 "riscv_insts_zbb.sail"
                 "riscv_insts_zbc.sail"
@@ -142,6 +144,7 @@ foreach (xlen IN ITEMS 32 64)
                 "riscv_fdext_control.sail"
                 "riscv_smcntrpmf.sail"
                 "riscv_sys_reservation.sail"
+                "riscv_sdext_control.sail"
                 "riscv_sys_control.sail"
             )
 
@@ -176,6 +179,7 @@ foreach (xlen IN ITEMS 32 64)
                 "riscv_regs.sail"
                 "riscv_pc_access.sail"
                 "riscv_sys_regs.sail"
+                "riscv_sdext_regs.sail"
                 "riscv_pmp_regs.sail"
                 "riscv_pmp_control.sail"
                 "riscv_ext_regs.sail"

model/CMakeLists.txt

@@ -31,6 +31,12 @@ function csr_full_read_callback(_) = ()
 val trap_callback = pure {c: "trap_callback"} : unit -> unit
 function trap_callback(_) = ()
 
+val debug_entry_callback = pure {c: "debug_entry_callback"} : unit -> unit
+function debug_entry_callback(_) = ()
+
+val debug_exit_callback = pure {c: "debug_exit_callback"} : unit -> unit
+function debug_exit_callback(_) = ()
+
 // Overloads for easier use of callbacks
 function csr_name_write_callback(name : string, value : xlenbits) -> unit = {
   let csr = csr_name_map(name);

model/riscv_callbacks.sail

@@ -329,6 +329,10 @@ enum clause extension = Ext_Smcntrpmf
 mapping clause extensionName = Ext_Smcntrpmf <-> "smcntrpmf"
 function clause hartSupports(Ext_Smcntrpmf) = config extensions.Smcntrpmf.supported
 
+// Debug
+enum clause extension = Ext_Sdext
+function clause hartSupports(Ext_Sdext) = config extensions.Sdext.supported
+
 let extensions_ordered_for_isa_string = [
   // Single letter extensions.
   Ext_M,

model/riscv_extensions.sail

@@ -20,6 +20,9 @@ union ExecutionResult = {
   Illegal_Instruction            : unit,
   Trap                           : (Privilege, ctl_result, xlenbits),
   Memory_Exception               : (virtaddr, ExceptionType),
+  Enter_Debug_Mode               : debug_entry_cause,
+  Exit_Debug_Abstract_Command    : unit,
+  Exit_Debug_Mode                : unit,
 
   // Did not retire for custom reason.
   Ext_CSR_Check_Failure          : unit,

model/riscv_inst_retire.sail

@@ -25,11 +25,16 @@ mapping clause encdec = UTYPE(imm, rd, op)
 
 function clause execute (UTYPE(imm, rd, op)) = {
   let off : xlenbits = sign_extend(imm @ 0x000);
-  X(rd) = match op {
-    LUI   => off,
-    AUIPC => get_arch_pc() + off
-  };
-  RETIRE_SUCCESS
+  match op {
+    LUI   => { X(rd) = off; RETIRE_SUCCESS },
+    AUIPC => {
+      if   in_debug_abstract_command() & ~(debug_is_pc_instr_legal())
+      then return Illegal_Instruction();
+
+      X(rd) = get_arch_pc() + off;
+      RETIRE_SUCCESS
+    },
+  }
 }
 
 mapping utype_mnemonic : uop <-> string = {
@@ -64,6 +69,8 @@ function clause execute (JAL(imm, rd)) = {
   match ext_control_check_pc(target) {
     Ext_ControlAddr_Error(e) => Ext_ControlAddr_Check_Failure(e),
     Ext_ControlAddr_OK(target) => {
+      if   in_debug_abstract_command() & ~(debug_is_legal_ct_target(target))
+      then return Illegal_Instruction();
       /* Perform standard alignment check */
       let target_bits = bits_of(target);
       if bit_to_bool(target_bits[1]) & not(currentlyEnabled(Ext_Zca)) then {
@@ -123,6 +130,9 @@ function clause execute (BTYPE(imm, rs2, rs1, op)) = {
     match ext_control_check_pc(target) {
       Ext_ControlAddr_Error(e) => Ext_ControlAddr_Check_Failure(e),
       Ext_ControlAddr_OK(target) => {
+        if   in_debug_abstract_command() & ~(debug_is_legal_ct_target(target))
+        then return Illegal_Instruction();
+
         let target_bits = bits_of(target);
         if bit_to_bool(target_bits[1]) & not(currentlyEnabled(Ext_Zca)) then {
           Memory_Exception(target, E_Fetch_Addr_Align())
@@ -521,6 +531,9 @@ mapping clause encdec = ECALL()
   <-> 0b000000000000 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011
 
 function clause execute ECALL() = {
+  if   in_debug_abstract_command()
+  then return debug_mode_ecall_hook();
+
   let t : sync_exception =
     struct { trap = match (cur_privilege) {
                       User       => E_U_EnvCall(),
@@ -541,6 +554,9 @@ mapping clause encdec = MRET()
   <-> 0b0011000 @ 0b00010 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011
 
 function clause execute MRET() = {
+  if   in_debug_abstract_command()
+  then return debug_mode_mret_hook();
+
   if   cur_privilege != Machine
   then Illegal_Instruction()
   else if not(ext_check_xret_priv(Machine))
@@ -560,6 +576,9 @@ mapping clause encdec = SRET()
   <-> 0b0001000 @ 0b00010 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011
 
 function clause execute SRET() = {
+  if   in_debug_abstract_command()
+  then return debug_mode_sret_hook();
+
   let sret_illegal : bool = match cur_privilege {
     User       => true,
     Supervisor => not(currentlyEnabled(Ext_S)) | mstatus[TSR] == 0b1,
@@ -583,8 +602,24 @@ union clause ast = EBREAK : unit
 mapping clause encdec = EBREAK()
   <-> 0b000000000001 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011
 
+function ebreak_into_debug() -> bool =
+  if   currentlyEnabled(Ext_Sdext)
+  then match cur_privilege {
+    User       => bool_bits(dcsr[EBreakU]),
+    Supervisor => bool_bits(dcsr[EBreakS]),
+    Machine    => bool_bits(dcsr[EBreakM]),
+    // TODO: VS/VU modes
+  }
+  else false
+
 function clause execute EBREAK() =
-  Memory_Exception(Virtaddr(PC), E_Breakpoint())
+  if in_debug_abstract_command() then {
+    Exit_Debug_Abstract_Command()
+  } else if ebreak_into_debug() then {
+    Enter_Debug_Mode(DBGEntry_EBreak)
+  } else {
+    Memory_Exception(Virtaddr(PC), E_Breakpoint())
+  }
 
 mapping clause assembly = EBREAK() <-> "ebreak"
 
@@ -595,7 +630,9 @@ mapping clause encdec = WFI()
   <-> 0b000100000101 @ 0b00000 @ 0b000 @ 0b00000 @ 0b1110011
 
 function clause execute WFI() =
-  match cur_privilege {
+  if   in_debug_abstract_command() | in_single_step()
+  then RETIRE_SUCCESS
+  else match cur_privilege {
     Machine    => Enter_Wait(WAIT_WFI),
     Supervisor => if   mstatus[TW] == 0b1
                   then Illegal_Instruction()

model/riscv_insts_base.sail

@@ -0,0 +1,18 @@
+/*=======================================================================================*/
+/*  This Sail RISC-V architecture model, comprising all files and                        */
+/*  directories except where otherwise noted is subject the BSD                          */
+/*  two-clause license in the LICENSE file.                                              */
+/*                                                                                       */
+/*  SPDX-License-Identifier: BSD-2-Clause                                                */
+/*=======================================================================================*/
+
+/* This file specifies the `dret` instruction in the `Sdext` extension. */
+
+union clause ast = DRET : unit
+
+mapping clause encdec = DRET()
+  <-> 0b01111011001000000000000001110011
+  when currentlyEnabled(Ext_Sdext) & ~(in_debug_abstract_command())
+
+function clause execute DRET() =
+  Exit_Debug_Mode()