Merge pull request #1046 from riscv/dmactive

DM should ignore some bits while abstract command is executing

debug_module.adoc

@@ -367,6 +367,8 @@ of {dm-data0}) or hart (e.g. contents of a register modified by a Program Buffe
 ====
 
 While an abstract command is executing ({abstractcs-busy} in {dm-abstractcs} is high), a debugger must not change {hartsel}, and must not write 1 to {dmcontrol-haltreq}, {dmcontrol-resumereq}, {dmcontrol-ackhavereset}, {dmcontrol-setresethaltreq}, or {dmcontrol-clrresethaltreq}.
+The hardware should not rely on this debugger behavior, but should enforce it by
+ignoring writes to these bits while {abstractcs-busy} is high.
 
 If an abstract command does not complete in the expected time and
 appears to be hung, the debugger can try to reset the hart (using {dmcontrol-hartreset} or {dmcontrol-ndmreset}).

xml/dm_registers.xml

@@ -177,7 +177,8 @@ same project unless stated otherwise.
         and at most 20. A debugger should discover `HARTSELLEN` by writing
         all ones to {hartsel} (assuming the maximum size) and reading back the
         value to see which bits were actually set. Debuggers must not change
-        {hartsel} while an abstract command is executing.
+        {hartsel} while an abstract command is executing. Hardware should enforce
+        this by ignoring changes to {hartsel} while {abstractcs-busy} is set.
 
         [NOTE]
         ====
@@ -219,6 +220,9 @@ same project unless stated otherwise.
             set.
 
             Writes apply to the new value of {hartsel} and {dmcontrol-hasel}.
+
+            Writes to this bit should be ignored while an abstract command is
+            executing.
         </field>
         <field name="resumereq" bits="30" access="W1" reset="-">
             Writing 1 causes the currently selected harts to resume once, if
@@ -228,6 +232,9 @@ same project unless stated otherwise.
             {dmcontrol-resumereq} is ignored if {dmcontrol-haltreq} is set.
 
             Writes apply to the new value of {hartsel} and {dmcontrol-hasel}.
+
+            Writes to this bit should be ignored while an abstract command is
+            executing.
         </field>
         <field name="hartreset" bits="29" access="WARL" reset="0">
             This optional field writes the reset bit for all the currently
@@ -253,6 +260,9 @@ same project unless stated otherwise.
             </value>
 
             Writes apply to the new value of {hartsel} and {dmcontrol-hasel}.
+
+            Writes to this bit should be ignored while an abstract command is
+            executing.
         </field>
         <field name="ackunavail" bits="27" access="W1" reset="-">
             <value v="0" name="nop">
@@ -315,12 +325,18 @@ same project unless stated otherwise.
             Writes apply to the new value of {hartsel} and {dmcontrol-hasel}.
 
             If {dmstatus-hasresethaltreq} is 0, this field is not implemented.
+
+            Writes to this bit should be ignored while an abstract command is
+            executing.
         </field>
         <field name="clrresethaltreq" bits="2" access="W1" reset="-">
             This optional field clears the halt-on-reset request bit for all
             currently selected harts.
 
             Writes apply to the new value of {hartsel} and {dmcontrol-hasel}.
+
+            Writes to this bit should be ignored while an abstract command is
+            executing.
         </field>
         <!-- Fields that apply to the entire DM. -->
         <field name="ndmreset" bits="1" access="R/W" reset="0">
@@ -340,13 +356,17 @@ same project unless stated otherwise.
             state change has completed.  Hardware may
             take an arbitrarily long time to complete activation or deactivation and will
             indicate completion by setting {dmcontrol-dmactive} to the requested value.
+            During this time, the DM may ignore any register writes.
 
             <value v="0" name="inactive">
             The module's state, including authentication mechanism,
             takes its reset values (the {dmcontrol-dmactive} bit is the only bit which can
             be written to something other than its reset value). Any accesses
             to the module may fail. Specifically, {dmstatus-version} might not return
             correct data.
+
+            When this value is written, the DM may ignore any other bits written
+            to {dmcontrol} in the same write.
             </value>
 
             <value v="1" name="active">
@@ -356,7 +376,7 @@ same project unless stated otherwise.
             No other mechanism should exist that may result in resetting the
             Debug Module after power up.
 
-            To place the Debug Module into a known state, a debugger may write 0 to {dmcontrol-dmactive},
+            To place the Debug Module into a known state, a debugger should write 0 to {dmcontrol-dmactive},
             poll until {dmcontrol-dmactive} is observed 0, write 1 to {dmcontrol-dmactive}, and
             poll until {dmcontrol-dmactive} is observed 1.