This register reports status for the overall Debug Module as well as the currently selected harts, as defined in {dmcontrol-hasel}. Its address will not change in the future, because it contains {dmstatus-version}. Unimplemented, or {dmcontrol-ndmreset} is zero and no ndmreset is currently in progress. {dmcontrol-ndmreset} is currently nonzero, or there is an ndmreset in progress. The per-hart `unavail` bits reflect the current state of the hart. The per-hart `unavail` bits are sticky. Once they are set, they will not clear until the debugger acknowledges them using {dmcontrol-ackunavail}. If 1, then there is an implicit `ebreak` instruction at the non-existent word immediately after the Program Buffer. This saves the debugger from having to write the `ebreak` itself, and allows the Program Buffer to be one word smaller. This must be 1 when {abstractcs-progbufsize} is 1. This field is 1 when all currently selected harts have been reset and reset has not been acknowledged for any of them. This field is 1 when at least one currently selected hart has been reset and reset has not been acknowledged for that hart. This field is 1 when all currently selected harts have their ((resume ack bit)) set. This field is 1 when any currently selected hart has its ((resume ack bit)) set. This field is 1 when all currently selected harts do not exist in this hardware platform. This field is 1 when any currently selected hart does not exist in this hardware platform. This field is 1 when all currently selected harts are unavailable, or (if {dmstatus-stickyunavail} is 1) were unavailable without that being acknowledged. This field is 1 when any currently selected hart is unavailable, or (if {dmstatus-stickyunavail} is 1) was unavailable without that being acknowledged. This field is 1 when all currently selected harts are running. This field is 1 when any currently selected hart is running. This field is 1 when all currently selected harts are halted. This field is 1 when any currently selected hart is halted. Authentication is required before using the DM. The authentication check has passed. On components that don't implement authentication, this bit must be preset as 1. The authentication module is ready to process the next read/write to {dm-authdata}. The authentication module is busy. Accessing {dm-authdata} results in unspecified behavior. {dmstatus-authbusy} only becomes set in immediate response to an access to {dm-authdata}. 1 if this Debug Module supports halt-on-reset functionality controllable by the {dmcontrol-setresethaltreq} and {dmcontrol-clrresethaltreq} bits. 0 otherwise. {dm-confstrptr0}--{dm-confstrptr3} hold information which is not relevant to the configuration structure. {dm-confstrptr0}--{dm-confstrptr3} hold the address of the configuration structure. There is no Debug Module present. There is a Debug Module and it conforms to version 0.11 of this specification. There is a Debug Module and it conforms to version 0.13 of this specification. There is a Debug Module and it conforms to version 1.0 of this specification. There is a Debug Module but it does not conform to any available version of this spec. This register controls the overall Debug Module as well as the currently selected harts, as defined in {dmcontrol-hasel}. [[hartsel]] (((hartsel))) Throughout this document we refer to {hartsel}, which is {dmcontrol-hartselhi} combined with {dmcontrol-hartsello}. While the spec allows for 20 {hartsel} bits, an implementation may choose to implement fewer than that. The actual width of {hartsel} is called `HARTSELLEN`. It must be at least 0 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. Hardware should enforce this by ignoring changes to {hartsel} while {abstractcs-busy} is set. [NOTE] ==== There are separate {dmcontrol-setresethaltreq} and {dmcontrol-clrresethaltreq} bits so that it is possible to write {dm-dmcontrol} without changing the halt-on-reset request bit for each selected hart, when not all selected harts have the same configuration. ==== On any given write, a debugger may only write 1 to at most one of the following bits: {dmcontrol-resumereq}, {dmcontrol-hartreset}, {dmcontrol-ackhavereset}, {dmcontrol-setresethaltreq}, and {dmcontrol-clrresethaltreq}. The others must be written 0. [[resethaltreq]] (((resethaltreq))) {resethaltreq} is an optional internal bit of per-hart state that cannot be read, but can be written with {dmcontrol-setresethaltreq} and {dmcontrol-clrresethaltreq}. [[keepalive]] (((keepalive))) {keepalive} is an optional internal bit of per-hart state. When it is set, it suggests that the hardware should attempt to keep the hart available for the debugger, e.g. by keeping it from entering a low-power state once powered on. Even if the bit is implemented, hardware might not be able to keep a hart available. The bit is written through {dmcontrol-setkeepalive} and {dmcontrol-clrkeepalive}. For forward compatibility, {dmstatus-version} will always be readable when bit 1 ({dmcontrol-ndmreset}) is 0 and bit 0 ({dmcontrol-dmactive}) is 1. Writing 0 clears the halt request bit for all currently selected harts. This may cancel outstanding halt requests for those harts. Writing 1 sets the halt request bit for all currently selected harts. Running harts will halt whenever their halt request bit 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. Writing 1 causes the currently selected harts to resume once, if they are halted when the write occurs. It also clears the resume ack bit for those harts. {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. This optional field writes the reset bit for all the currently selected harts. To perform a reset the debugger writes 1, and then writes 0 to deassert the reset signal. While this bit is 1, the debugger must not change which harts are selected. If this feature is not implemented, the bit always stays 0, so after writing 1 the debugger can read the register back to see if the feature is supported. Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. No effect. Clears `havereset` for any 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. No effect. Clears `unavail` for any selected harts that are currently available. Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. Selects the definition of currently selected harts. There is a single currently selected hart, that is selected by {hartsel}. There may be multiple currently selected harts -- the hart selected by {hartsel}, plus those selected by the hart array mask register. An implementation which does not implement the hart array mask register must tie this field to 0. A debugger which wishes to use the hart array mask register feature should set this bit and read back to see if the functionality is supported. The low 10 bits of {hartsel}: the DM-specific index of the hart to select. This hart is always part of the currently selected harts. The high 10 bits of {hartsel}: the DM-specific index of the hart to select. This hart is always part of the currently selected harts. This optional field sets {keepalive} for all currently selected harts, unless {dmcontrol-clrkeepalive} is simultaneously set to 1. Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. This optional field clears {keepalive} for all currently selected harts. Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. This optional field writes the halt-on-reset request bit for all currently selected harts, unless {dmcontrol-clrresethaltreq} is simultaneously set to 1. When set to 1, each selected hart will halt upon the next deassertion of its reset. The halt-on-reset request bit is not automatically cleared. The debugger must write to {dmcontrol-clrresethaltreq} to clear it. 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. 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. This bit controls the reset signal from the DM to the rest of the hardware platform. The signal should reset every part of the hardware platform, including every hart, except for the DM and any logic required to access the DM. To perform a hardware platform reset the debugger writes 1, and then writes 0 to deassert the reset. This bit serves as a reset signal for the Debug Module itself. After changing the value of this bit, the debugger must poll {dm-dmcontrol} until {dmcontrol-dmactive} has taken the requested value before performing any action that assumes the requested {dmcontrol-dmactive} 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. 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. The module functions normally. 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 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. Implementations may pay attention to this bit to further aid debugging, for example by preventing the Debug Module from being power gated while debugging is active. This register gives information about the hart currently selected by {hartsel}. This register is optional. If it is not present it should read all-zero. If this register is included, the debugger can do more with the Program Buffer by writing programs which explicitly access the `data` and/or `dscratch` registers. Number of `dscratch` registers available for the debugger to use during program buffer execution, starting from {csr-dscratch0}. The debugger can make no assumptions about the contents of these registers between commands. The `data` registers are shadowed in the hart by CSRs. Each CSR is DXLEN bits in size, and corresponds to a single argument, per <<tab:datareg>>. The `data` registers are shadowed in the hart's memory map. Each register takes up 4 bytes in the memory map. If {hartinfo-dataaccess} is 0: Number of CSRs dedicated to shadowing the `data` registers. If {hartinfo-dataaccess} is 1: Number of 32-bit words in the memory map dedicated to shadowing the `data` registers. Since there are at most 12 `data` registers, the value in this register must be 12 or smaller. If {hartinfo-dataaccess} is 0: The number of the first CSR dedicated to shadowing the `data` registers. If {hartinfo-dataaccess} is 1: Address of RAM where the data registers are shadowed. This address is sign extended giving a range of -2048 to 2047, easily addressed with a load or store using `x0` as the address register. This register selects which of the 32-bit portion of the hart array mask register (see xref:hartarraymask[]) is accessible in {dm-hawindow}. The high bits of this field may be tied to 0, depending on how large the array mask register is. E.g. on a hardware platform with 48 harts only bit 0 of this field may actually be writable. This register provides R/W access to a 32-bit portion of the hart array mask register (see xref:hartarraymask[]). The position of the window is determined by {dm-hawindowsel}. I.e. bit 0 refers to hart {dm-hawindowsel} latexmath:[$* 32$], while bit 31 refers to hart {dm-hawindowsel} latexmath:[$* 32 + 31$]. Since some bits in the hart array mask register may be constant 0, some bits in this register may be constant 0, depending on the current value of {dm-hawindowsel}. Writing this register while an abstract command is executing causes {abstractcs-cmderr} to become 1 (busy) once the command completes ({abstractcs-busy} becomes 0). [NOTE] ==== {abstractcs-datacount} must be at least 1 to support RV32 harts, 2 to support RV64 harts, or 4 to support RV128 harts. ==== Size of the Program Buffer, in 32-bit words. Valid sizes are 0 - 16. There is no abstract command currently being executed. An abstract command is currently being executed. This bit is set as soon as {dm-command} is written, and is not cleared until that command has completed. This optional bit controls whether program buffer and abstract memory accesses are performed with the exact and full set of permission checks that apply based on the current architectural state of the hart performing the access, or with a relaxed set of permission checks (e.g. PMP restrictions are ignored). The details of the latter are implementation-specific. Full permission checks apply. Relaxed permission checks apply. Gets set if an abstract command fails. The bits in this field remain set until they are cleared by writing 1 to them. No abstract command is started until the value is reset to 0. This field only contains a valid value if {abstractcs-busy} is 0. No error. An abstract command was executing while {dm-command}, {dm-abstractcs}, or {dm-abstractauto} was written, or when one of the `data` or `progbuf` registers was read or written. This status is only written if {abstractcs-cmderr} contains 0. The command in {dm-command} is not supported. It may be supported with different options set, but it will not be supported at a later time when the hart or system state are different. An exception occurred while executing the command (e.g. while executing the Program Buffer). The abstract command couldn't execute because the hart wasn't in the required state (running/halted), or unavailable. The abstract command failed due to a bus error (e.g. alignment, access size, or timeout). Reserved for future use. The command failed for another reason. Number of `data` registers that are implemented as part of the abstract command interface. Valid sizes are 1 -- 12. Writes to this register cause the corresponding abstract command to be executed. Writing this register while an abstract command is executing causes {abstractcs-cmderr} to become 1 (busy) once the command completes (busy becomes 0). If {abstractcs-cmderr} is non-zero, writes to this register are ignored. [NOTE] ==== {abstractcs-cmderr} inhibits starting a new command to accommodate debuggers that, for performance reasons, send several commands to be executed in a row without checking {abstractcs-cmderr} in between. They can safely do so and check {abstractcs-cmderr} at the end without worrying that one command failed but then a later command (which might have depended on the previous one succeeding) passed. ==== The type determines the overall functionality of this abstract command. This field is interpreted in a command-specific manner, described for each abstract command. This register is optional. Including it allows more efficient burst accesses. A debugger can detect whether it is supported by setting bits and reading them back. If this register is implemented then bits corresponding to implemented progbuf and data registers must be writable. Other bits must be hard-wired to 0. If this register is written while an abstract command is executing then the write is ignored and {abstractcs-cmderr} becomes 1 (busy) once the command completes (busy becomes 0). When a bit in this field is 1, read or write accesses to the corresponding `progbuf` word cause the DM to act as if the current value in {dm-command} was written there again after the access to `progbuf` completes. When a bit in this field is 1, read or write accesses to the corresponding `data` word cause the DM to act as if the current value in {dm-command} was written there again after the access to `data` completes. When {dmstatus-confstrptrvalid} is set, reading this register returns bits 31:0 of the configuration structure pointer. Reading the other `confstrptr` registers returns the upper bits of the address. When system bus access is implemented, this must be an address that can be used with the System Bus Access module. Otherwise, this must be an address that can be used to access the configuration structure from the hart with ID 0. If {dmstatus-confstrptrvalid} is 0, then the `confstrptr` registers hold identifier information which is not further specified in this document. The configuration structure itself is a data structure of the same format as the data structure pointed to by `mconfigptr` as described in the Privileged Spec. When {dmstatus-confstrptrvalid} is set, reading this register returns bits 63:32 of the configuration structure pointer. See {dm-confstrptr0} for more details. When {dmstatus-confstrptrvalid} is set, reading this register returns bits 95:64 of the configuration structure pointer. See {dm-confstrptr0} for more details. When {dmstatus-confstrptrvalid} is set, reading this register returns bits 127:96 of the configuration structure pointer. See {dm-confstrptr0} for more details. If there is more than one DM accessible on this DMI, this register contains the base address of the next one in the chain, or 0 if this is the last one in the chain. {dm-data0} through {dm-data11} are registers that may be read or changed by abstract commands. {abstractcs-datacount} indicates how many of them are implemented, starting at {dm-data0}, counting up. <<tab:datareg>> shows how abstract commands use these registers. Accessing these registers while an abstract command is executing causes {abstractcs-cmderr} to be set to 1 (busy) if it is 0. Attempts to write them while {abstractcs-busy} is set does not change their value. The values in these registers might not be preserved after an abstract command is executed. The only guarantees on their contents are the ones offered by the command in question. If the command fails, no assumptions can be made about the contents of these registers. {dm-progbuf0} through {dm-progbuf15} must provide write access to the optional program buffer. It may also be possible for the debugger to read from the program buffer through these registers. If reading is not supported, then all reads return 0. {abstractcs-progbufsize} indicates how many `progbuf` registers are implemented starting at {dm-progbuf0}, counting up. Accessing these registers while an abstract command is executing causes {abstractcs-cmderr} to be set to 1 (busy) if it is 0. Attempts to write them while {abstractcs-busy} is set does not change their value. This register serves as a 32-bit serial port to/from the authentication module. When {dmstatus-authbusy} is clear, the debugger can communicate with the authentication module by reading or writing this register. There is no separate mechanism to signal overflow/underflow. This register contains DM control and status bits that didn't easily fit in {dm-dmcontrol} and {dm-dmstatus}. All are optional. If halt groups are not implemented, then {dmcs2-group} will always be 0 when {dmcs2-grouptype} is 0. If resume groups are not implemented, then {dmcs2-grouptype} will remain 0 even after 1 is written there. The DM external triggers available to add to halt groups may be the same as or distinct from the DM external triggers available to add to resume groups. The remaining fields in this register configure halt groups. The remaining fields in this register configure resume groups. This field contains the currently selected DM external trigger. If a non-existent trigger value is written here, the hardware will change it to a valid one or 0 if no DM external triggers exist. When {dmcs2-hgselect} is 0, contains the group of the hart specified by {hartsel}. When {dmcs2-hgselect} is 1, contains the group of the DM external trigger selected by {dmcs2-dmexttrigger}. The value written to this field is ignored unless {dmcs2-hgwrite} is also written 1. Group numbers are contiguous starting at 0, with the highest number being implementation-dependent, and possibly different between different group types. Debuggers should read back this field after writing to confirm they are using a hart group that is supported. If groups aren't implemented, then this entire field is 0. When 1 is written and {dmcs2-hgselect} is 0, for every selected hart the DM will change its group to the value written to {dmcs2-group}, if the hardware supports that group for that hart. Implementations may also change the group of a minimal set of unselected harts in the same way, if that is necessary due to a hardware limitation. When 1 is written and {dmcs2-hgselect} is 1, the DM will change the group of the DM external trigger selected by {dmcs2-dmexttrigger} to the value written to {dmcs2-group}, if the hardware supports that group for that trigger. Writing 0 has no effect. Operate on harts. Operate on DM external triggers. If there are no DM external triggers, this field must be tied to 0. Each bit in this read-only register indicates whether one specific hart is halted or not. Unavailable/nonexistent harts are not considered to be halted. This register might not be present if fewer than 2 harts are connected to this DM. The LSB reflects the halt status of hart {hartsel[19:5],5'h0}, and the MSB reflects halt status of hart {hartsel[19:5],5'h1f}. Each bit in this read-only register indicates whether any of a group of harts is halted or not. Unavailable/nonexistent harts are not considered to be halted. This register might not be present if fewer than 33 harts are connected to this DM. The LSB reflects the halt status of harts {hartsel[19:10],10'h0} through {hartsel[19:10],10'h1f}. The MSB reflects the halt status of harts {hartsel[19:10],10'h3e0} through {hartsel[19:10],10'h3ff}. Each bit in this read-only register indicates whether any of a group of harts is halted or not. Unavailable/nonexistent harts are not considered to be halted. This register might not be present if fewer than 1025 harts are connected to this DM. The LSB reflects the halt status of harts {hartsel[19:15],15'h0} through {hartsel[19:15],15'h3ff}. The MSB reflects the halt status of harts {hartsel[19:15],15'h7c00} through {hartsel[19:15],15'h7fff}. Each bit in this read-only register indicates whether any of a group of harts is halted or not. Unavailable/nonexistent harts are not considered to be halted. This register might not be present if fewer than 32769 harts are connected to this DM. The LSB reflects the halt status of harts 20'h0 through 20'h7fff. The MSB reflects the halt status of harts 20'hf8000 through 20'hfffff. The System Bus interface conforms to mainline drafts of this spec older than 1 January, 2018. The System Bus interface conforms to this version of the spec. Other values are reserved for future versions. Set when the debugger attempts to read data while a read is in progress, or when the debugger initiates a new access while one is already in progress (while {sbcs-sbbusy} is set). It remains set until it's explicitly cleared by the debugger. While this field is set, no more system bus accesses can be initiated by the Debug Module. When 1, indicates the system bus manager is busy. (Whether the system bus itself is busy is related, but not the same thing.) This bit goes high immediately when a read or write is requested for any reason, and does not go low until the access is fully completed. Writes to {dm-sbcs} while {sbcs-sbbusy} is high result in undefined behavior. A debugger must not write to {dm-sbcs} until it reads {sbcs-sbbusy} as 0. When 1, every write to {dm-sbaddress0} automatically triggers a system bus read at the new address. Select the access size to use for system bus accesses. 8-bit 16-bit 32-bit 64-bit 128-bit If {sbcs-sbaccess} has an unsupported value when the DM starts a bus access, the access is not performed and {sbcs-sberror} is set to 4. When 1, `sbaddress` is incremented by the access size (in bytes) selected in {sbcs-sbaccess} after every system bus access. When 1, every read from {dm-sbdata0} automatically triggers a system bus read at the (possibly auto-incremented) address. When the Debug Module's system bus manager encounters an error, this field gets set. The bits in this field remain set until they are cleared by writing 1 to them. While this field is non-zero, no more system bus accesses can be initiated by the Debug Module. An implementation may report ``Other'' (7) for any error condition. There was no bus error. There was a timeout. A bad address was accessed. There was an alignment error. An access of unsupported size was requested. Other. Width of system bus addresses in bits. (0 indicates there is no bus access support.) 1 when 128-bit system bus accesses are supported. 1 when 64-bit system bus accesses are supported. 1 when 32-bit system bus accesses are supported. 1 when 16-bit system bus accesses are supported. 1 when 8-bit system bus accesses are supported. If {sbcs-sbasize} is 0, then this register is not present. When the system bus manager is busy, writes to this register will set {sbcs-sbbusyerror} and don't do anything else. If {sbcs-sberror} is 0, {sbcs-sbbusyerror} is 0, and {sbcs-sbreadonaddr} is set then writes to this register start the following: . Set {sbcs-sbbusy}. . Perform a bus read from the new value of `sbaddress`. . If the read succeeded and {sbcs-sbautoincrement} is set, increment `sbaddress`. . Clear {sbcs-sbbusy}. Accesses bits 31:0 of the physical address in `sbaddress`. If {sbcs-sbasize} is less than 33, then this register is not present. When the system bus manager is busy, writes to this register will set {sbcs-sbbusyerror} and don't do anything else. Accesses bits 63:32 of the physical address in `sbaddress` (if the system address bus is that wide). If {sbcs-sbasize} is less than 65, then this register is not present. When the system bus manager is busy, writes to this register will set {sbcs-sbbusyerror} and don't do anything else. Accesses bits 95:64 of the physical address in `sbaddress` (if the system address bus is that wide). If {sbcs-sbasize} is less than 97, then this register is not present. When the system bus manager is busy, writes to this register will set {sbcs-sbbusyerror} and don't do anything else. Accesses bits 127:96 of the physical address in `sbaddress` (if the system address bus is that wide). If all of the `sbaccess` bits in {dm-sbcs} are 0, then this register is not present. Any successful system bus read updates `sbdata`. If the width of the read access is less than the width of `sbdata`, the contents of the remaining high bits may take on any value. If either {sbcs-sberror} or {sbcs-sbbusyerror} isn't 0 then accesses do nothing. If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. Writes to this register start the following: . Set {sbcs-sbbusy}. . Perform a bus write of the new value of `sbdata` to `sbaddress`. . If the write succeeded and {sbcs-sbautoincrement} is set, increment `sbaddress`. . Clear {sbcs-sbbusy}. Reads from this register start the following: . "Return" the data. . Set {sbcs-sbbusy}. . If {sbcs-sbreadondata} is set: // TODO: This doesn't work right, but it does work in asiidoclive .. Perform a system bus read from the address contained in `sbaddress`, placing the result in `sbdata`. .. If {sbcs-sbautoincrement} is set and the read was successful, increment `sbaddress`. . Clear {sbcs-sbbusy}. Only {dm-sbdata0} has this behavior. The other `sbdata` registers have no side effects. On systems that have buses wider than 32 bits, a debugger should access {dm-sbdata0} after accessing the other `sbdata` registers. Accesses bits 31:0 of `sbdata`. If {sbcs-sbaccess64} and {sbcs-sbaccess128} are 0, then this register is not present. If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. Accesses bits 63:32 of `sbdata` (if the system bus is that wide). This register only exists if {sbcs-sbaccess128} is 1. If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. Accesses bits 95:64 of `sbdata` (if the system bus is that wide). This register only exists if {sbcs-sbaccess128} is 1. If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. Accesses bits 127:96 of `sbdata` (if the system bus is that wide). This optional register may be used for non-standard features. Future version of the debug spec will not use this address. The optional {dm-custom0} through {dm-custom15} registers may be used for non-standard features. Future versions of the debug spec will not use these addresses.