diff --git a/debug_module.adoc b/debug_module.adoc index 4edd6aa2..077ca930 100644 --- a/debug_module.adoc +++ b/debug_module.adoc @@ -1,4 +1,4 @@ -[[]] +[[dm]] == Debug Module (DM) (non-ISA extension) The Debug Module implements a translation interface between abstract @@ -43,7 +43,7 @@ Specification", instead of the "RISC-V Debug Specification". A single DM can debug up to latexmath:[$2^{20}$] harts. -[[i]] +[[dmi]] === Debug Module Interface (DMI) Debug Modules are subordinates on a bus called the Debug Module @@ -81,10 +81,10 @@ and then clears it. The actual reset may start as soon as the bit is asserted, but may start an arbitrarily long time after the bit is deasserted. The reset itself may also take an arbitrarily long time. While the reset is on-going, harts are either in the running state, -indicating it’s possible to perform some abstract commands during this -time, or in the unavailable state, indicating it’s not possible to +indicating it's possible to perform some abstract commands during this +time, or in the unavailable state, indicating it's not possible to perform any abstract commands during this time. Once a hart's reset is -complete, `havereset` becomes set. When a hart comes out of reset and <> or <> +complete, `havereset` becomes set. When a hart comes out of reset and {dmcontrol-haltreq} or <> are set, the hart will immediately enter Debug Mode (halted state). Otherwise, if the hart was initially running it will execute normally (running state) and if the hart was initially halted it should now be @@ -97,7 +97,7 @@ has actually begun. ==== The Debug Module's own state and registers should only be reset at -power-up and while <> in <> is 0. If there is another mechanism to reset the DM, this mechanism must also reset all the harts accessible to the DM. +power-up and while {dmcontrol-dmactive} in <> is 0. If there is another mechanism to reset the DM, this mechanism must also reset all the harts accessible to the DM. Due to clock and power domain crossing issues, it might not be possible to perform arbitrary DMI accesses across hardware platform reset. While <> or any external reset is asserted, the only supported DM operations are reading and writing <>. The behavior of other accesses is undefined. @@ -106,7 +106,7 @@ When harts have been reset, they must set a sticky `havereset` state bit. The conceptual `havereset` state bits can be read for selected harts in <> and <> in <>. These bits must be set regardless of the cause of the reset. The `havereset` bits for the selected harts can be cleared by -writing 1 to <> in <>. The `havereset` bits might or might not be cleared when <> is low. +writing 1 to <> in <>. The `havereset` bits might or might not be cleared when {dmcontrol-dmactive} is low. [[selectingharts]] === Selecting Harts @@ -152,7 +152,7 @@ to the hart selected by <>. Every hart that can be selected is in exactly one of the following four DM states: non-existent, unavailable, running, or halted. Which state -the selected harts are in is reflected by <>, <>, <>, <>, <>, <>, <>, and <>. +the selected harts are in is reflected by <>, <>, {dmstatus-allunavail}, {dmstatus-anyunavail}, <>, <>, <>, and <>. Harts are nonexistent if they will never be part of this hardware platform, no matter how long a user waits. E.g. in a simple single-hart @@ -187,7 +187,7 @@ Which states a hart that is reset goes through is implementation dependent. Harts may be unavailable while reset is asserted, and some time after reset is deasserted. They might transition to running for some time after reset is deasserted. Finally they end up either running -or halted, depending on <> and <>. +or halted, depending on {dmcontrol-haltreq} and <>. [[runcontrol]] === Run Control @@ -199,7 +199,7 @@ to 0, except for resume ack, which may reset to either 0 or 1. The DM receives halted, running, and havereset signals from each hart. The debugger can observe the state of resume ack in <> and <>, and the state of halted, running, and havereset signals in <>, <>, <>, <>, <>, and <>. The state of the other bits cannot be observed directly. -When a debugger writes 1 to <>, each selected hart's halt request bit is +When a debugger writes 1 to {dmcontrol-haltreq}, each selected hart's halt request bit is set. When a running hart, or a hart just coming out of reset, sees its halt request bit high, it responds by halting, deasserting its running signal, and asserting its halted signal. Halted harts ignore their halt @@ -223,7 +223,7 @@ is true regardless of the reset's cause. The hart's halt-on-reset request bit remains set until cleared by the debugger writing 1 to <> while the hart is selected, or by DM reset. If the DM is reset while a hart is halted, it is UNSPECIFIED whether that hart -resumes. Debuggers should use <> to explicitly resume harts before clearing <> and disconnecting. +resumes. Debuggers should use <> to explicitly resume harts before clearing {dmcontrol-dmactive} and disconnecting. [[hrgroups]] === Halt Groups, Resume Groups, and External Triggers @@ -363,14 +363,14 @@ failed, the debugger has to look at the state of the DM (e.g. contents of <>) or hart (e.g. contents of a register modified by a Program Buffer program) to determine which one failed. ==== -Before starting an abstract command, a debugger must ensure that <>, <>, and <> are all 0. +Before starting an abstract command, a debugger must ensure that {dmcontrol-haltreq}, <>, and <> are all 0. -While an abstract command is executing (<> in > is high), a debugger must not change <>, and must not write 1 to <>, <>, <>, <>, or <>. +While an abstract command is executing (<> in > is high), a debugger must not change <>, and must not write 1 to {dmcontrol-haltreq}, <>, <>, <>, or <>. 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 <> or <>). If that doesn't clear <>, then it can try resetting the Debug Module -(using <>). +(using {dmcontrol-dmactive}). If an abstract command is started while the selected hart is unavailable or if a hart becomes unavailable while executing an abstract command, @@ -469,11 +469,11 @@ accesses. <> shows which bits in `sbdata` are used for each access s [%autowidth,align="center",float="center",cols=">,<",options="header"] |=== |Access Size | Data Bits -| 8 | <> bits 7:0 -| 16 | <> bits 15:0 -| 32 | <> -| 64 | <>, <> -| 128 | <>, <>, <>, <> +| 8 | {dm-sbdata0} bits 7:0 +| 16 | {dm-sbdata0} bits 15:0 +| 32 | {dm-sbdata0} +| 64 | <>, {dm-sbdata0} +| 128 | <>, <>, <>, {dm-sbdata0} |=== Depending on the microarchitecture, data accessed through System Bus @@ -535,8 +535,8 @@ be ignored, with the following mandatory exceptions: . <> in <> is readable. . <> in <> is readable. -. <> in <> is readable. -. <> in <> is readable and writable. +. {tinfo-version} in <> is readable. +. {dmcontrol-dmactive} in <> is readable and writable. . <> is readable and writable. Implementations where it's not possible to unlock the DM by using <> should not implement that register. @@ -547,18 +547,18 @@ To detect the version of the Debug Module with a minimum of side effects, use the following procedure: . Read <>. -. If <> is 0 or <> is 1: -.. Write <>, preserving <>, <>, <>, and <> from the value that was read, setting <>, and clearing all the other bits. -.. Read <>until <> is high. -. Read <>, which contains <>. +. If {dmcontrol-dmactive} is 0 or <> is 1: +.. Write <>, preserving <>, <>, <>, and <> from the value that was read, setting {dmcontrol-dmactive}, and clearing all the other bits. +.. Read <>until {dmcontrol-dmactive} is high. +. Read <>, which contains {tinfo-version}. If it was necessary to clear <>, this might have the following side effects: -. <> is cleared, potentially preventing a halt request made by a previous debugger from taking effect. +. {dmcontrol-haltreq} is cleared, potentially preventing a halt request made by a previous debugger from taking effect. . <> is cleared, potentially preventing a resume request made by a previous debugger from taking effect. . <> is deasserted, releasing the hardware platform from reset if a previous debugger had set it. -. <> is asserted, releasing the DM from reset. This in itself is not +. {dmcontrol-dmactive} is asserted, releasing the DM from reset. This in itself is not observable by any harts. This procedure is guaranteed to work in future versions of this spec. diff --git a/introduction.adoc b/introduction.adoc index c9848bc7..07423ebb 100644 --- a/introduction.adoc +++ b/introduction.adoc @@ -117,16 +117,16 @@ Version 0.13. Changes that fix a bug in the spec: -. Fix order of operations described in <>. +. Fix order of operations described in {dm-sbdata0}. https://github.com/riscv/riscv-debug-spec/pull/392[#392] . Resume ack is set after resume, in <>. https://github.com/riscv/riscv-debug-spec/pull/400[#400] -. <> applies to <> . https://github.com/riscv/riscv-debug-spec/pull/402[#402] -. <> only applies when action=0. +. {textra32-sselect} applies to {textra32-svalue} . https://github.com/riscv/riscv-debug-spec/pull/402[#402] +. {tcontrol-mte} only applies when action=0. https://github.com/riscv/riscv-debug-spec/pull/411[#411] -. <> does not affect Argument Width. +. {accessmemory-aamsize} does not affect Argument Width. https://github.com/riscv/riscv-debug-spec/pull/420[#420] -. Clarify that harts halt out of reset if <> =1. +. Clarify that harts halt out of reset if {dmcontrol-haltreq} =1. https://github.com/riscv/riscv-debug-spec/pull/419[#419] ===== Incompatible Changes from 0.13 to 1.0 @@ -138,21 +138,21 @@ order to implement 1.0: . Make haltsum0 optional if there is only one hart. https://github.com/riscv/riscv-debug-spec/pull/505[#505] . System bus autoincrement only happens if an access actually takes place. -(<>) https://github.com/riscv/riscv-debug-spec/pull/507[#507] -. Bump <> to 3. https://github.com/riscv/riscv-debug-spec/pull/512[#512] -, Require debugger to poll <> after lowering it. +({dm-sbdata0}) https://github.com/riscv/riscv-debug-spec/pull/507[#507] +. Bump {tinfo-version} to 3. https://github.com/riscv/riscv-debug-spec/pull/512[#512] +, Require debugger to poll {dmcontrol-dmactive} after lowering it. https://github.com/riscv/riscv-debug-spec/pull/566[#566] -. Add <> to <> . https://github.com/riscv/riscv-debug-spec/pull/574[#574] -. When a selected trigger is disabled, <> and <> can be written with any value supported by any of the types this trigger supports. +. Add {icount-pending} to {csr-icount} . https://github.com/riscv/riscv-debug-spec/pull/574[#574] +. When a selected trigger is disabled, {csr-tdata2} and {csr-tdata3} can be written with any value supported by any of the types this trigger supports. https://github.com/riscv/riscv-debug-spec/pull/721[#721] -. <> fields only apply to breakpoint traps, not any trap. +. {csr-tcontrol} fields only apply to breakpoint traps, not any trap. https://github.com/riscv/riscv-debug-spec/pull/723[#723] -. If <> is greater than 0, then <> (previously called <>.``hit``) now contains 0 when a trigger fires more than one instruction after the +. If {tinfo-version} is greater than 0, then {mcontrol6-hit0} (previously called {csr-mcontrol}.``hit``) now contains 0 when a trigger fires more than one instruction after the instruction that matched. (This information is now reflected in .) https://github.com/riscv/riscv-debug-spec/pull/795[#795] -. If <> is greater than 0, then bit 20 of <> is no longer used for timing information. (Previously the bit was called <>.``timing``.) +. If {tinfo-version} is greater than 0, then bit 20 of {csr-mcontrol6} is no longer used for timing information. (Previously the bit was called {csr-mcontrol}.``timing``.) https://github.com/riscv/riscv-debug-spec/pull/807[#807] -. If <> is greater than 0, then the encodings of <> for sizes greater than 64 bit have changed. +. If {tinfo-version} is greater than 0, then the encodings of {mcontrol6-size} for sizes greater than 64 bit have changed. https://github.com/riscv/riscv-debug-spec/pull/807[#807] ===== Minor Changes from 0.13 to 1.0 @@ -160,33 +160,33 @@ https://github.com/riscv/riscv-debug-spec/pull/807[#807] Changes that slightly modify defined behavior. Technically backwards incompatible, but unlikely to be noticeable: -. <> only applies to hart-local counters. +. {dcsr-stopcount} only applies to hart-local counters. https://github.com/riscv/riscv-debug-spec/pull/405[#405] -. <> may be invalid when <>=0. +. {tinfo-version} may be invalid when {dmcontrol-dmactive}=0. https://github.com/riscv/riscv-debug-spec/pull/414[#414] -. Address triggers (<>) may fire on any accessed address. +. Address triggers ({csr-mcontrol}) may fire on any accessed address. https://github.com/riscv/riscv-debug-spec/pull/421[#421] -. All trigger registers (<>) are optional. https://github.com/riscv/riscv-debug-spec/pull/431[#431] -. When extending IR, <> still is all ones. +. All trigger registers (<>) are optional. https://github.com/riscv/riscv-debug-spec/pull/431[#431] +. When extending IR, {dtm-bypass} still is all ones. https://github.com/riscv/riscv-debug-spec/pull/437[#437] -. <> and <> are WARL. https://github.com/riscv/riscv-debug-spec/pull/458[#458] -. NMIs are disabled by <>. +. {dcsr-ebreaks} and {dcsr-ebreaku} are WARL. https://github.com/riscv/riscv-debug-spec/pull/458[#458] +. NMIs are disabled by {dcsr-stepie}. https://github.com/riscv/riscv-debug-spec/pull/465[#465] . R/W1C fields should be cleared by writing every bit high. https://github.com/riscv/riscv-debug-spec/pull/472[#472] -. Specify trigger priorities in <> relative to exceptions. +. Specify trigger priorities in <> relative to exceptions. https://github.com/riscv/riscv-debug-spec/pull/478[#478] -. Time may pass before <> becomes high. +. Time may pass before {dmcontrol-dmactive} becomes high. https://github.com/riscv/riscv-debug-spec/pull/500[#500] . Clear MPRV when resuming into lower privilege mode. https://github.com/riscv/riscv-debug-spec/pull/503[#503] . Halt state may not be preserved across reset. https://github.com/riscv/riscv-debug-spec/pull/504[#504] -. Hardware should clear trigger action when <> is cleared and action is 1. +. Hardware should clear trigger action when {tdata1-dmode} is cleared and action is 1. https://github.com/riscv/riscv-debug-spec/pull/501[#501] -. Change quick access exceptions to halt the target in <>. +. Change quick access exceptions to halt the target in <>. https://github.com/riscv/riscv-debug-spec/pull/585[#585] -. Writing 0 to <> forces a state where <> and <> are writable. +. Writing 0 to {csr-tdata1} forces a state where {csr-tdata2} and {csr-tdata3} are writable. https://github.com/riscv/riscv-debug-spec/pull/598[#598] . Solutions to deal with reentrancy in <> prevent triggers from _matching_, not merely _firing_. This primarily affects behavior. @@ -200,39 +200,39 @@ New backwards-compatible feature that did not exist before: . Add halt groups and external triggers in <>. https://github.com/riscv/riscv-debug-spec/pull/404[#404] -. Reserve some DMI space for non-standard use. See <>, and <> through . +. Reserve some DMI space for non-standard use. See {dm-custom}, and {dm-custom0} through . https://github.com/riscv/riscv-debug-spec/pull/406[#406] -. Reserve trigger <> values for non-standard use. +. Reserve trigger {tdata1-type} values for non-standard use. https://github.com/riscv/riscv-debug-spec/pull/417[#417] -. Add <> bit to <>. https://github.com/riscv/riscv-debug-spec/pull/408[#408] +. Add {itrigger-nmi} bit to {csr-itrigger}. https://github.com/riscv/riscv-debug-spec/pull/408[#408] and https://github.com/riscv/riscv-debug-spec/pull/709[#709] . Recommend matching on every accessed address. https://github.com/riscv/riscv-debug-spec/pull/449[#449] . Add resume groups in <>. https://github.com/riscv/riscv-debug-spec/pull/506[#506] -. Add <> . https://github.com/riscv/riscv-debug-spec/pull/536[#536] -. Move <>, renaming original to <>, and create <>. +. Add {abstractcs-relaxedpriv} . https://github.com/riscv/riscv-debug-spec/pull/536[#536] +. Move {csr-scontext}, renaming original to {csr-mscontext}, and create {csr-hcontext}. https://github.com/riscv/riscv-debug-spec/pull/535[#535] -. Add <>, deprecating <>. +. Add {csr-mcontrol6}, deprecating {csr-mcontrol}. https://github.com/riscv/riscv-debug-spec/pull/538[#538] -. Add hypervisor support: <>, <>, <>, <>, <>, <>, and <>. +. Add hypervisor support: {dcsr-ebreakvs}, {dcsr-ebreakvu}, {dcsr-v}, {csr-hcontext}, {csr-mcontrol}, {csr-mcontrol6}, and {virt-priv}. https://github.com/riscv/riscv-debug-spec/pull/549[#549] -. Optionally make <> and <> sticky, controlled by <>. +. Optionally make {dmstatus-anyunavail} and {dmstatus-allunavail} sticky, controlled by {dmstatus-stickyunavail}. https://github.com/riscv/riscv-debug-spec/pull/520[#520] -. Add <> to support trigger module external trigger inputs. +. Add {csr-tmexttrigger} to support trigger module external trigger inputs. https://github.com/riscv/riscv-debug-spec/pull/543[#543] -. Describe <> and <> behavior with atomic instructions. +. Describe {csr-mcontrol} and {csr-mcontrol6} behavior with atomic instructions. https://github.com/riscv/riscv-debug-spec/pull/561[#561] . Trigger hit bits must be set on fire, may be set on match. https://github.com/riscv/riscv-debug-spec/pull/593[#593] -. Add <> and <> to <> and <>. +. Add {textra32-sbytemask} and {textra32-sbytemask} to {csr-textra32} and {csr-textra64}. https://github.com/riscv/riscv-debug-spec/pull/588[#588] . Allow debugger to request harts stay alive with keepalive bit in -<>. +{dmcontrol-setkeepalive}. https://github.com/riscv/riscv-debug-spec/pull/592[#592] -. Add <> to allow a debugger to determine when ndmreset is complete. +. Add {dmstatus-ndmresetpending} to allow a debugger to determine when ndmreset is complete. https://github.com/riscv/riscv-debug-spec/pull/594[#594] -. Add <> to support triggers from an interrupt controller. +. Add {tmexttrigger-intctl} to support triggers from an interrupt controller. https://github.com/riscv/riscv-debug-spec/pull/599[#599] ===== Incompatible Changes During 1.0 Stable @@ -240,7 +240,7 @@ https://github.com/riscv/riscv-debug-spec/pull/599[#599] Backwards-incompatible changes between two versions that are both called 1.0 stable. -. <> was moved from <> to <>, and is now subject to the mode bits in that trigger. +. {itrigger-nmi} was moved from {csr-etrigger} to {csr-itrigger}, and is now subject to the mode bits in that trigger. . https://github.com/riscv/riscv-debug-spec/pull/728[#728] introduced Message Registers, which were later removed in @@ -248,7 +248,7 @@ https://github.com/riscv/riscv-debug-spec/pull/878[#878]. . It may not be possible to read the contents of the Program Buffer using the `progbuf` registers. https://github.com/riscv/riscv-debug-spec/pull/731[#731] -. <> fields apply to all traps, not just breakpoint traps. This reverts +. {csr-tcontrol} fields apply to all traps, not just breakpoint traps. This reverts https://github.com/riscv/riscv-debug-spec/pull/723[#723]. https://github.com/riscv/riscv-debug-spec/pull/880[#880] @@ -279,7 +279,7 @@ The total number of bits in the field are shown below it. After the graphic follows a table which for each field lists its name, description, allowed accesses, and reset value. The allowed accesses are -listed in <>. The reset value is either a constant or "Preset." The latter means it is an implementation-specific legal value. +listed in <>. The reset value is either a constant or "Preset." The latter means it is an implementation-specific legal value. Parts of the register which are currently unused are labeled with the number 0. Software must only write 0 to those fields, and ignore their @@ -297,6 +297,18 @@ and are also listed in the index on page <>. include::build/sample_registers.adoc[] +[[tab:access]] +.Register Access Abbreviations +[width=75%,align="center",float="center",cols="<,^"] +|=== +|R | Read-only. +|R/W | Read/Write. +|R/W1C | Read/Write Ones to Clear. Writing 0 to every bit has no effect. Writing 1 to every bit clears the field. The result of other writes is undefined. +|WARZ | Write any, read zero. A debugger may write any value. When read this field returns 0. +|W1 | Write-only. Only writing 1 has an effect. When read the returned value should be 0. +|WARL | Write any, read legal. A debugger may write any value. If a value is unsupported, the implementation converts the value to one that is supported. +|=== + === Background There are several use cases for dedicated debugging hardware, both in