Added paragraphs and notes about hardware loops impact on application…

…, exceptions handlers and debugger.

Signed-off-by: Pascal Gouedo <[email protected]>

docs/source/corev_hw_loop.rst

@@ -138,3 +138,46 @@ it is executed 10x10 times. Whereas the outermost loop, from startO to (endO - 4
 executes 10 times the innermost loop and adds 2 to the register %[j].
 At the end of the loop, the register %[i] contains 300 and the register %[j] contains 20.
 
+.. _hwloop-exceptions_handlers:
+
+Hardware loops impact on application, exceptions handlers and debugger
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Application and ebreak/ecall exception handlers
+-----------------------------------------------
+
+When an ebreak or an ecall instruction is used in an application, special care should be given for those instruction handlers in case they are placed as the last instruction of an HWLoop.
+Those handlers should manage MEPC and lpcountX CSRs updates because an hw loop early-exit could happen if not done.
+
+At the end of the handlers after restoring the context/CSRs, a piece of smart code should be added (by order of piority):
+
+1. if MEPC is equal to "lpend0 - 4", then MPEC should be set to lpstart0 and lpcount0 should be decremented by 1 if strictly higher than 0,
+2. if MEPC is equal to "lpend1 - 4", then MPEC should be set to lpstart1 and lpcount1 should be decremented by 1 if strictly higher than 0,
+3. if (lpstart0 <= MEPC < lpend0 - 4) or (lpstart1 <= MEPC < lpend1 - 4), then MPEC should be incremented by 4,
+4. if instruction at MEPC location is either ecall or ebreak, MPEC should be incremented by 4,
+5. if instruction at MEPC location location is c.ebreak, MPEC should be incremented by 2.
+
+The 2 last cases are the standard ones when ebreak/ecall are not inside an HWLopp.
+
+Interrupt handlers
+------------------
+
+When an interrupt is happening on the last HWLoop instruction, its execution is cancelled, its address is saved in MEPC and its execution will be resumed when returning from interrupt handler.
+There is nothing special to be done in those interrupt handlers with respect to MEPC and lpcountX updates, they will be correctly managed by design when executing this last HWLoop instruction after interrupt handler execution.
+
+Illegal instruction exception handler
+-------------------------------------
+
+Depending if an application is going to resume or not after Illegal instruction exception handler, same MEPC/HWLoops CSRs management than ebreak/ecall could be necessary.
+
+Debugger
+--------
+
+If ebreak is used to enter in Debug Mode (:ref:`ebreak_scenario_2`) and put at the last instruction location of an HWLoop (not very likely to happen), same management than above should be done but on DPC rather than on MEPC.
+
+When ebreak instruction is used as Software Breakpoint by a debugger when in debug mode and is placed at the last instruction location of an HWLoop in instruction memory, no special management is foreseen.
+When executing the Software Breakpoint/ebreak instruction, control is given back to the debugger which will manage the different cases.
+For instance in Single-Step case, original instruction is put back in instruction memory, a Single-Step command is executed on this last instruction (with desgin updating PC and lpcountX to correct values) and Software Breakpoint/ebreak is put back by the debugger in memory.
+
+When ecall instruction is used by a debugger to execute System Calls and is placed at the last instruction location of an HWLoop in instruction memory, debugger ecall handler in debug rom should do the same than described above for application case.
+

docs/source/debug.rst

@@ -162,6 +162,8 @@ The EBREAK instruction description is distributed across several RISC-V specific
 `RISC-V Priveleged Specification <https://github.com/riscv/riscv-isa-manual/releases/tag/Ratified-IMFDQC-and-Priv-v1.11>`_,
 `RISC-V ISA <https://github.com/riscv/riscv-isa-manual/releases/tag/Ratified-IMAFDQC>`_. The following is a summary of the behavior for three common scenarios.
 
+.. _ebreak_scenario_1:
+
 Scenario 1 : Enter Exception
 """"""""""""""""""""""""""""
 
@@ -173,10 +175,14 @@ Executing the EBREAK instruction when the core is **not** in Debug Mode and the
 To properly return from the exception, the ebreak handler will need to increment the MEPC to the next instruction.
 This requires querying the size of the ebreak instruction that was used to enter the exception (16 bit c.ebreak or 32 bit ebreak). 
 
+As mentioned in :ref:`hwloop-exceptions_handlers`, some additional cases exist for MEPC update when ebreak is the last instruction of an Hardware Loop.
+
 .. note::
 
   The CV32E40P does not support MTVAL CSR register which would have saved the value of the instruction for exceptions. This may be supported on a future core.
 
+.. _ebreak_scenario_2:
+
 Scenario 2 : Enter Debug Mode
 """""""""""""""""""""""""""""
 
@@ -187,11 +193,15 @@ Executing the EBREAK instruction when the core is **not** in Debug Mode and the
 
 Similar to the exception scenario above, the debugger will need to increment the DPC to the next instruction before returning from Debug Mode.
 
+There is no forseseen situtation where it would be needed to enter in Debug Mode only on the last instruction of an Hardware Loop but just in case this is mentioned in :ref:`hwloop-exceptions_handlers` as well.
+
 .. note::
 
   The default value of DCSR.EBREAKM is 0 and the DCSR is only accessible in Debug Mode. To enter Debug Mode from EBREAK,
   the user will first need to enter Debug Mode through some other means, such as from the external ``debug_req_i``, and set DCSR.EBREAKM.
 
+.. _ebreak_scenario_3:
+
 Scenario 3 : Exit Program Buffer & Restart Debug Code
 """""""""""""""""""""""""""""""""""""""""""""""""""""