From 9108540759c57e3672a3d59116062fa9512cfc1f Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Wed, 20 Dec 2023 13:28:05 -0500 Subject: [PATCH] Added includes of registers. Added include statements for core_registers.adoc and sw_registers.adoc. --- Sdext.adoc | 139 ++++++++++++++++++++++++----------------------------- 1 file changed, 62 insertions(+), 77 deletions(-) diff --git a/Sdext.adoc b/Sdext.adoc index 0289fc5a..5328f518 100644 --- a/Sdext.adoc +++ b/Sdext.adoc @@ -1,4 +1,4 @@ -[[sec:core_debug]] +[[core_debug]] == Sdext (ISA Extension) This chapter describes the Sdext ISA extension. It must be implemented @@ -27,74 +27,63 @@ is not specified here. When executing code due to an abstract command, the hart stays in Debug Mode and the following apply: -All implemented instructions operate just as they do in M-mode, unless +. All implemented instructions operate just as they do in M-mode, unless an exception is mentioned in this list. - -All operations are executed with machine mode privilege, except that +. All operations are executed with machine mode privilege, except that additional Debug Mode CSRs are accessible and in may be ignored -according to . Full permission checks, or a relaxed set of permission -checks, will apply according to . - -All interrupts (including NMI) are masked. - -Traps don’t take place. Instead, they end execution of the program +according to <>. Full permission checks, or a relaxed set of permission +checks, will apply according to <>. +. All interrupts (including NMI) are masked. +. Traps don't take place. Instead, they end execution of the program buffer and the hart remains in Debug Mode. Because they do not trap to M-mode, they do not update registers such as , `mepc`, `mcause`, -` mtval`, `mtval2`, and `mtinst`. The same is true for the equivalent +`mtval`, `mtval2`, and `mtinst`. The same is true for the equivalent privileged registers that are updated when trapping to other modes. Registers that may be updated as part of execution before the exception are allowed to be updated. For example, vector load/store instructions which raise exceptions may partially update the destination register and set `vstart` appropriately. - -Triggers don’t match or fire. - -If is 0 then counters continue. If it is 1 then counters are stopped. - -If is 0 then continues to update. If it is 1 then will not update. It -will resynchronize with after leaving Debug Mode. - -Instructions that place the hart into a stalled state act as a `nop`. +. Triggers don't match or fire. +. If <> is 0 then counters continue. If it is 1 then counters are stopped. +. If <> is 0 then continues to update. If it is 1 then will not update. It will resynchronize with after leaving Debug Mode. +. Instructions that place the hart into a stalled state act as a `nop`. This includes `wfi`, `wrs.sto`, and `wrs.nto`. - -Almost all instructions that change the privilege mode have  behavior. +. Almost all instructions that change the privilege mode have  behavior. This includes `ecall`, `mret`, `sret`, and `uret`. (To change the privilege mode, the debugger can write and in ). The only exception is `ebreak`, which ends execution of the Program Buffer when executed. - -All control transfer instructions may act as illegal instructions if +. All control transfer instructions may act as illegal instructions if their destination is in the Program Buffer. If one such instruction acts as an illegal instruction, all such instructions must act as illegal instructions. - -All control transfer instructions may act as illegal instructions if +. All control transfer instructions may act as illegal instructions if their destination is outside the Program Buffer. If one such instruction acts as an illegal instruction, all such instructions must act as illegal instructions. - -Instructions that depend on the value of the PC (e.g. `auipc`) may act +. Instructions that depend on the value of the PC (e.g. `auipc`) may act as illegal instructions. +. Effective XLEN is DXLEN. +. Forward progress is guaranteed. -Effective XLEN is DXLEN. - -Forward progress is guaranteed. - -When , the external debugger can set MPRV and MPP appropriately to have +[NOTE] +==== +When <>, the external debugger can set MPRV and MPP appropriately to have hardware perform memory accesses with the appropriate endianness, -address translation, permission checks, and PMP/PMA checks (subject to -). This is also the only way to access all of physical memory when -34-bit physical addresses are supported on a Sv32 hart. If hardware ties -to 0 then the external debugger is expected to simulate all the effects +address translation, permission checks, and PMP/PMA checks (subject to <>). This is also the only way to access all of physical memory when +34-bit physical addresses are supported on a Sv32 hart. If hardware ties <> to 0 then the external debugger is expected to simulate all the effects of MPRV, including any extensions that affect memory accesses. For these -reasons it is recommended to tie to 1. +reasons it is recommended to tie <> to 1. +==== === Load-Reserved/Store-Conditional Instructions The reservation registered by an `lr` instruction on a memory address may be lost when entering Debug Mode or while in Debug Mode. This means that there may be no forward progress if Debug Mode is entered between -`lr` and ` sc` pairs. +`lr` and `sc` pairs. +[NOTE] +==== This is a behavior that debug users must be aware of. If they have a breakpoint set between a `lr` and `sc` pair, or are stepping through such code, the `sc` may never succeed. Fortunately in general use there @@ -103,30 +92,31 @@ it will quickly notice that the reservation is not occurring. The solution in that case is to set a breakpoint on the first instruction after the `sc` and run to it. A higher level debugger may choose to automate this. +==== === Wait for Interrupt Instruction If halt is requested while `wfi` is executing, then the hart must leave -the stalled state, completing this instruction’s execution, and then +the stalled state, completing this instruction's execution, and then enter Debug Mode. === Wait-on-Reservation-Set Instructions If halt is requested while `wrs.sto` or `wrs.nto` is executing, then the -hart must leave the stalled state, completing this instruction’s +hart must leave the stalled state, completing this instruction's execution, and then enter Debug Mode. === Single Step -[[stepBit]] +[[stepbit]] ==== Step Bit In Dcsr This method is only available to external debuggers, and is the preferred way to single step. An external debugger can cause a halted hart to execute a single -instruction or trap and then re-enter Debug Mode by setting before -resuming. If is set when a hart resumes then it will single step, +instruction or trap and then re-enter Debug Mode by setting <> before +resuming. If <> is set when a hart resumes then it will single step, regardless of the reason for resuming. If control is transferred to a trap handler while executing the @@ -138,7 +128,7 @@ be executed at all. If executing or fetching the instruction causes a trigger to fire with action=1, Debug Mode is re-entered immediately after that trigger has -fired. In that case is set to 2 (trigger) instead of 4 (single step). +fired. In that case <> is set to 2 (trigger) instead of 4 (single step). Whether the instruction is executed or not depends on the specific configuration of the trigger. @@ -152,32 +142,28 @@ If the instruction being stepped over would normally stall the hart, then instead the instruction is treated as a `nop`. This includes `wfi`, `wrs.sto`, and `wrs.nto`. -[[stepIcount]] +[[stepicount]] ==== Icount Trigger -Native debuggers won’t have access to , but can use the trigger by -setting to 1. +Native debuggers won't have access to <>, but can use the <> trigger by setting <> to 1. This approach does have some limitations: -Interrupts will fire as usual. Debuggers that want to disable interrupts -while stepping must disable them by changing , and specially handle -instructions that read . - -`wfi` instructions are not treated specially and might take a very long +. Interrupts will fire as usual. Debuggers that want to disable interrupts +while stepping must disable them by changing `mstatus`, and specially handle +instructions that read 'mstatus'. +. `wfi` instructions are not treated specially and might take a very long time to complete. This mechanism cleanly supports a system which supports multiple privilege levels, where the OS or a debug stub runs in M-Mode while the program being debugged runs in a less privileged mode. Systems that only -support M-Mode can use as well, but count must be able to count several -instructions (depending on the software implementation). See Section -link:#nativestep[[nativestep]]. +support M-Mode can use <> as well, but count must be able to count several instructions (depending on the software implementation). See [[nativestep]]. === Reset -If the halt signal (driven by the hart’s halt request bit in the Debug -Module) or are asserted when a hart comes out of reset, the hart must +If the halt signal (driven by the hart's halt request bit in the Debug +Module) or <> are asserted when a hart comes out of reset, the hart must enter Debug Mode before executing any instructions, but after performing any initialization that would usually happen before the first instruction is executed. @@ -186,38 +172,31 @@ instruction is executed. When a hart halts: -is updated. - -and are set to reflect current privilege mode. - -is set to the next instruction that should be executed. - -If the current instruction can be partially executed and should be +. <,cause>> is updated. +. <> and <> are set to reflect current privilege mode. +. <> is set to the next instruction that should be executed. +. If the current instruction can be partially executed and should be restarted to complete, then the relevant state for that is updated. E.g. if a halt occurs during a partially executed vector instruction, then -`vstart` is updated, and is updated to the address of the partially +`vstart` is updated, and <> is updated to the address of the partially executed instruction. This is analogous to how vector instructions behave for exceptions. - -The hart enters Debug Mode. +. The hart enters Debug Mode. === Resume When a hart resumes: -changes to the value stored in . - -The current privilege mode and virtualization mode are changed to that -specified by and . - -If the new privilege mode is less privileged than M-mode, in is cleared. - -The hart is no longer in debug mode. +. `pc` changes to the value stored in <>. +. The current privilege mode and virtualization mode are changed to that +specified by <> and <>. +. If the new privilege mode is less privileged than M-mode, `MPRV` in 'mstatus` is cleared. +. The hart is no longer in debug mode. === XLEN While in Debug Mode, XLEN is DXLEN. It is up to the debugger to -determine the XLEN during normal program execution (by looking at ) and +determine the XLEN during normal program execution (by looking at 'misa') and to clearly communicate this to the user. [[debreg]] @@ -230,5 +209,11 @@ opcodes and optionally also using abstract debug commands. Attempts to access an unimplemented Core Debug Register raise an illegal instruction exception. +These registers are only accessible from Debug Mode. + +include::core_registers.adoc[] + [[virtreg]] === Virtual Debug Registers + +include::sw_registers.adoc[]