diff --git a/build/Makefile b/build/Makefile index 91265133..dc82c995 100644 --- a/build/Makefile +++ b/build/Makefile @@ -64,9 +64,9 @@ build-no-container: build-registers build-registers: $(REGISTERS_ADOC) %.adoc: ../xml/%.xml $(REGISTERS_PY) - ../registers.py --adoc $< > $@ + ../registers.py --adoc $@ --adoc-definitions $(patsubst %.adoc,%-def.adoc,$@) $< clean: @echo "Cleaning up generated files..." - rm -f $(PDF_RESULT) + rm -f $(PDF_RESULT) $(REGISTERS_ADOC) @echo "Cleanup completed." diff --git a/registers.py b/registers.py index fb064722..02ea7021 100755 --- a/registers.py +++ b/registers.py @@ -361,7 +361,8 @@ def toLatexIdentifier( *args ): return text def toAdocIdentifier( *args ): - text = "".join( (a or "").lower() for a in args ) + text = "-".join( (a or "").lower().rstrip("_") for a in args ) + text = re.sub( "\s+", "", text ) return text def toCIdentifier( text ): @@ -381,6 +382,17 @@ def write_definitions( fd, registers ): toLatexIdentifier( registers.prefix, regid, f.name ), f.name ) ) +def write_adoc_definitions( fd, registers ): + for r in registers.registers: + regid = r.short or r.label + if r.define: + macroName = toAdocIdentifier( registers.prefix, regid ) + fd.write( f":{macroName}: <<{macroName},{r.short or r.label}>>\n" ) + for f in r.fields: + if f.define: + macroName = toAdocIdentifier( regid, f.name ) + fd.write( f":{macroName}: <<{macroName},{f.name}>>\n" ) + class Macro: def __init__(self, name, expressionText): self.name = name @@ -805,6 +817,7 @@ def print_latex_register( registers ): def remove_indent( text ): return "\n".join( line.lstrip() for line in text.splitlines() ) + def add_continuations(text): lines = text.splitlines() result = [] @@ -815,8 +828,7 @@ def add_continuations(text): result.append(current_line) return "\n".join(result) -def print_adoc( registers, source ): - print(f"// Registers auto-generated on {datetime.now()} from {source}") +def write_adoc( fd, registers ): sub = "=" * registers.depth for r in registers.registers: if not r.fields and not r.description: @@ -825,31 +837,31 @@ def print_adoc( registers, source ): if r.short: # TODO: Check that (((foo))) renders as ((foo)) inside parens if r.address: - print(f"==={sub} {r.name} ((({r.short})), at {r.address})") + fd.write(f"==={sub} {r.name} ((({r.short})), at {r.address})\n") else: - print(f"==={sub} {r.name} ((({r.short})))") + fd.write(f"==={sub} {r.name} ((({r.short})))\n") # TODO: confirm that index works else: if r.address: - print(f"==={sub} ((`{r.name}`)) (at {r.address})") + fd.write(f"==={sub} ((`{r.name}`)) (at {r.address})\n") else: - print(f"==={sub} ((`{r.name}`))") - print() + fd.write(f"==={sub} ((`{r.name}`))\n") + fd.write("\n") if r.label and r.define: - print("[[%s]]" % toAdocIdentifier(registers.prefix, r.label)) - print(remove_indent(r.description)) - print() + fd.write("[[%s]]\n" % toAdocIdentifier(registers.prefix, r.label)) + fd.write(remove_indent(r.description)) + fd.write("\n") if r.fields: if registers.prefix == "CSR_": if int(r.address, 0) >= 0xc00: - print("This CSR is read-only.") + fd.write("This CSR is read-only.\n") elif all(f.access in ('R', '0') for f in r.fields): - print("Writing this read/write CSR has no effect.") + fd.write("Writing this read/write CSR has no effect.\n") else: - print("This CSR is read/write.") + fd.write("This CSR is read/write.\n") elif all(f.access in ('R', '0') for f in r.fields): - print("This entire register is read-only.") + fd.write("This entire register is read-only.\n") # todo: use wavedrom to draw the picture # print("\\begin{center}") @@ -913,28 +925,24 @@ def print_adoc( registers, source ): columns += [("^1", "Reset", lambda f: f.reset)] if any( f.description for f in r.fields ): - #print("\\tabletail{\\hline \\multicolumn{%d}{|r|}" % len(columns)) - #print(" {{Continued on next page}} \\\\ \\hline}") cols = ",".join(c[0] for c in columns) - print(f'[float="center",align="center",cols="{cols}",options="header"]') - print("|===") + fd.write(f'[float="center",align="center",cols="{cols}",options="header"]\n') + fd.write("|===\n") - print("|" + " |".join(c[1] for c in columns)) + fd.write("|" + " |".join(c[1] for c in columns) + "\n") for f in r.fields: if f.description or f.values: identifier = toAdocIdentifier(r.short or r.label, f.name) - print(f"|[[{identifier},{identifier}]] `{columns[0][2](f)}`") + fd.write(f"|[[{identifier},{identifier}]] `{columns[0][2](f)}`\n") for c in columns[1:]: - print("|" + add_continuations(remove_indent( c[2](f) ))) + fd.write("|" + add_continuations(remove_indent( c[2](f) )) + "\n") - print("|===") - print() + fd.write("|===\n") + fd.write("\n") -def print_adoc_index( registers, source ): - print(f"// Index auto-generated on {datetime.now()} from {source}") - - print(remove_indent(registers.description)) +def write_adoc_index( fd, registers ): + fd.write(remove_indent(registers.description)) columns = [ ("Address", "1"), @@ -942,10 +950,10 @@ def print_adoc_index( registers, source ): if any(r.sdesc for r in registers.registers): columns.append(("Description", "6")) - print(f"[[{toAdocIdentifier(registers.prefix, registers.label)}]]") - print('[cols="' + ",".join(c[1] for c in columns) + '",options="header"]') - print("|===") - print("|" + " |".join(c[0] for c in columns)) + fd.write(f"[[{toAdocIdentifier(registers.prefix, registers.label)}]]\n") + fd.write('[cols="' + ",".join(c[1] for c in columns) + '",options="header"]\n') + fd.write("|===\n") + fd.write("|" + " |".join(c[0] for c in columns) + "\n") for r in sorted( registers.registers, key=cmp_to_key(lambda a, b: compare_address(a.address, b.address))): @@ -954,10 +962,10 @@ def print_adoc_index( registers, source ): else: name = r.name if r.sdesc: - print("|%s | %s | %s" % ( r.address, name, r.sdesc )) + fd.write("|%s |%s |%s\n" % ( r.address, name, r.sdesc )) else: - print("|%s | %s" % ( r.address, name )) - print("|===") + fd.write("|%s |%s\n" % ( r.address, name )) + fd.write("|===\n") def main(): parser = argparse.ArgumentParser() @@ -967,8 +975,10 @@ def main(): 'start/end positions.' ) parser.add_argument( '--custom', action='store_true', help='Use custom LaTeX.' ) - parser.add_argument( '--adoc', action='store_true', - help='Use asciidoc.' ) + parser.add_argument( '--adoc', + help='Write asciidoc registers to the named file.' ) + parser.add_argument( '--adoc-definitions', + help='Write asciidoc register style definitions to the named file.' ) parser.add_argument( '--definitions', help='Write register style definitions to the named file.' ) parser.add_argument( '--cheader', @@ -997,17 +1007,37 @@ def main(): write_cheader( open( parsed.cheader, "w" ), registers ) if parsed.chisel: write_chisel( open( parsed.chisel, "w" ), registers ) - if not registers.skip_index: - if parsed.adoc: - print_adoc_index( registers, parsed.path ) - else: - print_latex_index( registers ) + if not registers.skip_index and not parsed.adoc: + print_latex_index( registers ) if parsed.register: assert(0) print_latex_register( registers ) if parsed.custom: print_latex_custom( registers ) if parsed.adoc: - print_adoc( registers, parsed.path ) + with open( parsed.adoc, "w" ) as fd: + fd.write(f"// Auto-generated on {datetime.now()} from {parsed.path}") + if not registers.skip_index: + write_adoc_index( fd, registers ) + write_adoc( fd, registers ) + if parsed.adoc_definitions: + with open( parsed.adoc_definitions, "w" ) as fd: + fd.write(f"// Auto-generated on {datetime.now()} from {parsed.path}") + write_adoc_definitions( fd, registers ) + + #sed_convert(registers) + +def sed_convert( registers ): + for r in registers.registers: + regid = r.short or r.label + if r.define: + latex = "\\\\R" + toLatexIdentifier( registers.prefix, regid ) + adoc = "{" + toAdocIdentifier( registers.prefix, regid ) + "}" + print(f"s/{latex}/{adoc}/g") + for f in r.fields: + if f.define: + latex = "\\\\F" + toLatexIdentifier( registers.prefix, regid, f.name ) + adoc = "{" + toAdocIdentifier( regid, f.name ) + "}" + print(f"s/{latex}/{adoc}/g") sys.exit( main() ) diff --git a/riscv-debug-header.adoc b/riscv-debug-header.adoc index 54d09bb7..12cbb4f7 100644 --- a/riscv-debug-header.adoc +++ b/riscv-debug-header.adoc @@ -67,6 +67,15 @@ Andy Wright, Bryan Wyatt, and Florian Zaruba. _This document is released under a Creative Commons Attribution 4.0 International License._ +// Include macros for registers and fields +include::build/abstract_commands-def.adoc[] +include::build/core_registers-def.adoc[] +include::build/dm_registers-def.adoc[] +include::build/hwbp_registers-def.adoc[] +include::build/jtag_registers-def.adoc[] +include::build/sample_registers-def.adoc[] +include::build/sw_registers-def.adoc[] + include::introduction.adoc[] include::overview.adoc[] include::debug_module.adoc[] diff --git a/xml/abstract_commands.xml b/xml/abstract_commands.xml index 402b074e..d8e0e691 100644 --- a/xml/abstract_commands.xml +++ b/xml/abstract_commands.xml @@ -4,27 +4,27 @@ \begin{steps}{This command gives the debugger access to CPU registers and allows it to execute the Program Buffer. It performs the following sequence of operations:} - \item If \FacAccessregisterWrite is clear and \FacAccessregisterTransfer is set, then copy data from - the register specified by \FacAccessregisterRegno into the {\tt arg0} region of + \item If {accessregister-write} is clear and {accessregister-transfer} is set, then copy data from + the register specified by {accessregister-regno} into the {\tt arg0} region of {\tt data}, and perform any side effects that occur when this register is read from M-mode. - \item If \FacAccessregisterWrite is set and \FacAccessregisterTransfer is set, then copy data from the + \item If {accessregister-write} is set and {accessregister-transfer} is set, then copy data from the {\tt arg0} region of {\tt data} into the register specified by - \FacAccessregisterRegno, and perform any side effects that occur when this register + {accessregister-regno}, and perform any side effects that occur when this register is written from M-mode. - \item If \FacAccessregisterAarpostincrement and - \FacAccessregisterTransfer are set, increment - \FacAccessregisterRegno. \FacAccessregisterRegno may also be - incremented if \FacAccessregisterAarpostincrement is set and - \FacAccessregisterTransfer is clear. - \item Execute the Program Buffer, if \FacAccessregisterPostexec is set. + \item If {accessregister-aarpostincrement} and + {accessregister-transfer} are set, increment + {accessregister-regno}. {accessregister-regno} may also be + incremented if {accessregister-aarpostincrement} is set and + {accessregister-transfer} is clear. + \item Execute the Program Buffer, if {accessregister-postexec} is set. \end{steps} - If any of these operations fail, \FdmAbstractcsCmderr is set and none of the + If any of these operations fail, {abstractcs-cmderr} is set and none of the remaining steps are executed. An implementation may detect an upcoming failure early, and fail the overall command before it reaches the step that would cause failure. If the failure is that the requested register - does not exist in the hart, \FdmAbstractcsCmderr must be set to 3 (exception). + does not exist in the hart, {abstractcs-cmderr} must be set to 3 (exception). Debug Modules must implement this command and must support read and write access to all GPRs when the selected hart is halted. @@ -50,7 +50,7 @@ \hline Numbers & Group Description \\ \hline - 0x0000 -- 0x0fff & CSRs. The ``PC'' can be accessed here through \RcsrDpc. + 0x0000 -- 0x0fff & CSRs. The ``PC'' can be accessed here through {csr-dpc}. \\ \hline 0x1000 -- 0x101f & GPRs \\ @@ -64,7 +64,7 @@ \end{table} \begin{commentary} - The encoding of \FacAccessregisterAarsize was chosen to match \FdmSbcsSbaccess in \RdmSbcs. + The encoding of {accessregister-aarsize} was chosen to match {sbcs-sbaccess} in {dm-sbcs}. \end{commentary} This command modifies {\tt arg0} only when a register is read. The @@ -87,8 +87,8 @@ Access the lowest 128 bits of the register. - If \FacAccessregisterAarsize specifies a size larger than the register's actual size, - then the access must fail. If a register is accessible, then reads of \FacAccessregisterAarsize + If {accessregister-aarsize} specifies a size larger than the register's actual size, + then the access must fail. If a register is accessible, then reads of {accessregister-aarsize} less than or equal to the register's actual size must be supported. Writing less than the full register may be supported, but what happens to the high bits in that case is \unspecified. @@ -102,17 +102,17 @@ - After a successful register access, \FacAccessregisterRegno is + After a successful register access, {accessregister-regno} is incremented. Incrementing past the highest supported value - causes \FacAccessregisterRegno to become \unspecified. Supporting + causes {accessregister-regno} to become \unspecified. Supporting this variant is optional. It is undefined whether the increment - happens when \FacAccessregisterTransfer is 0. + happens when {accessregister-transfer} is 0. No effect. This variant must be supported, and is the only - supported one if \FdmAbstractcsProgbufsize is 0. + supported one if {abstractcs-progbufsize} is 0. @@ -123,18 +123,18 @@ - Don't do the operation specified by \FacAccessregisterWrite. + Don't do the operation specified by {accessregister-write}. - Do the operation specified by \FacAccessregisterWrite. + Do the operation specified by {accessregister-write}. This bit can be used to just execute the Program Buffer without - having to worry about placing valid values into \FacAccessregisterAarsize or \FacAccessregisterRegno. + having to worry about placing valid values into {accessregister-aarsize} or {accessregister-regno}. - When \FacAccessregisterTransfer is set: + When {accessregister-transfer} is set: Copy data from the specified register into {\tt arg0} portion of {\tt data}. @@ -148,20 +148,20 @@ Number of the register to access, as described in Table~\ref{tab:regno}. - \RcsrDpc may be used as an alias for PC if this command is + {csr-dpc} may be used as an alias for PC if this command is supported on a non-halted hart. \begin{steps}{Perform the following sequence of operations:} - \item If the hart is halted, the command sets \FdmAbstractcsCmderr to ``halt/resume'' and does not continue. + \item If the hart is halted, the command sets {abstractcs-cmderr} to ``halt/resume'' and does not continue. \item Halt the hart. If the hart halts for some other reason (e.g. breakpoint), the command - sets \FdmAbstractcsCmderr to ``halt/resume'' and does not continue. + sets {abstractcs-cmderr} to ``halt/resume'' and does not continue. \item Execute the Program Buffer. - If an exception occurs, \FdmAbstractcsCmderr is set to + If an exception occurs, {abstractcs-cmderr} is set to ``exception,'' the Program Buffer execution ends, and the hart is - halted with \FcsrDcsrCause set to 3. + halted with {dcsr-cause} set to 3. \item If the Program Buffer executed without an exception, then resume the hart. \end{steps} @@ -183,13 +183,13 @@ registers, etc. The command performs the following sequence of operations:} \item Copy data from the memory location specified in {\tt arg1} into the - {\tt arg0} portion of {\tt data}, if \FacAccessregisterWrite is clear. + {\tt arg0} portion of {\tt data}, if {accessregister-write} is clear. \item Copy data from the {\tt arg0} portion of {\tt data} into the - memory location specified in {\tt arg1}, if \FacAccessregisterWrite is set. - \item If \FacAccessmemoryAampostincrement is set, increment {\tt arg1}. + memory location specified in {\tt arg1}, if {accessregister-write} is set. + \item If {accessmemory-aampostincrement} is set, increment {\tt arg1}. \end{steps} - If any of these operations fail, \FdmAbstractcsCmderr is set and none of the + If any of these operations fail, {abstractcs-cmderr} is set and none of the remaining steps are executed. An access may only fail if the hart, running M-mode code, might encounter that same failure when it attempts the same access. @@ -204,11 +204,11 @@ support memory accesses while the hart is halted. \begin{commentary} - The encoding of \FacAccessmemoryAamsize was chosen to match \FdmSbcsSbaccess in \RdmSbcs. + The encoding of {accessmemory-aamsize} was chosen to match {sbcs-sbaccess} in {dm-sbcs}. \end{commentary} This command modifies {\tt arg0} only when memory is read. It modifies - {\tt arg1} only if \FacAccessmemoryAampostincrement is set. The other {\tt data} + {\tt arg1} only if {accessmemory-aampostincrement} is set. The other {\tt data} registers are not changed. @@ -229,8 +229,8 @@ Debug Modules on systems without address translation (i.e. virtual addresses equal physical) - may optionally allow \FacAccessmemoryAamvirtual set to 1, which would produce the same result as - that same abstract command with \FacAccessmemoryAamvirtual cleared. + may optionally allow {accessmemory-aamvirtual} set to 1, which would produce the same result as + that same abstract command with {accessmemory-aamvirtual} cleared. @@ -256,7 +256,7 @@ After a memory access has completed, if this bit is 1, increment {\tt arg1} (which contains the address used) by the number of bytes - encoded in \FacAccessmemoryAamsize. + encoded in {accessmemory-aamsize}. Supporting this variant is optional, but highly recommended for performance reasons. diff --git a/xml/core_registers.xml b/xml/core_registers.xml index 93728987..df2df9fa 100755 --- a/xml/core_registers.xml +++ b/xml/core_registers.xml @@ -2,10 +2,10 @@ These registers are only accessible from Debug Mode. - Upon entry into Debug Mode, \FcsrDcsrV and \FcsrDcsrPrv are updated - with the privilege level the hart was previously in, and \FcsrDcsrCause + Upon entry into Debug Mode, {dcsr-v} and {dcsr-prv} are updated + with the privilege level the hart was previously in, and {dcsr-cause} is updated with the reason for Debug Mode entry. Other than these - fields and \FcsrDcsrNmip, the other fields of \RcsrDcsr are only + fields and {dcsr-nmip}, the other fields of {csr-dcsr} are only writable by the external debugger. \begin{steps}{Table~\ref{tab:dcsrcausepriority} shows the priorities of @@ -22,7 +22,7 @@ \label{tab:dcsrcausepriority} \begin{tabular}{|c|c|} \hline - \FcsrDcsrCause encoding & Cause \\ + {dcsr-cause} encoding & Cause \\ \hline 5 & resethaltreq \\ \hline @@ -46,11 +46,11 @@ an execute trigger with timing=after on an ebreak instruction is lower priority than the ebreak itself because the trigger will fire after the ebreak instruction. For the same reason, if a single instruction is - stepped with both icount and \FcsrDcsrStep then the \FcsrDcsrStep has + stepped with both icount and {dcsr-step} then the {dcsr-step} has priority. See table~\ref{tab:priority} for the relative priorities of triggers with respect to the ebreak instruction. - Most multi-hart implementations will probably hardwire \FcsrDcsrStoptime + Most multi-hart implementations will probably hardwire {dcsr-stoptime} to 0, as the implementation can get complicated and the benefit is small. \end{commentary} @@ -132,13 +132,13 @@ Interrupts (including NMI) are disabled during single stepping - with \FcsrDcsrStep set. + with {dcsr-step} set. This value should be supported. Interrupts (including NMI) are enabled during single stepping - with \FcsrDcsrStep set. + with {dcsr-step} set. Implementations may hard wire this bit to 0. @@ -172,7 +172,7 @@ leaving Debug Mode, \Rtime will reflect the latest value of \Rmtime again. - While all harts have \FcsrDcsrStoptime=1 and are in Debug Mode, + While all harts have {dcsr-stoptime}=1 and are in Debug Mode, \Rmtime is allowed to stop incrementing. @@ -182,7 +182,7 @@ Explains why Debug Mode was entered. When there are multiple reasons to enter Debug Mode in a single - cycle, hardware should set \FcsrDcsrCause to the cause with the highest + cycle, hardware should set {dcsr-cause} to the cause with the highest priority. See table~\ref{tab:dcsrcausepriority} for priorities. @@ -194,11 +194,11 @@ - The debugger requested entry to Debug Mode using \FdmDmcontrolHaltreq. + The debugger requested entry to Debug Mode using {dmcontrol-haltreq}. - The hart single stepped because \FcsrDcsrStep was set. + The hart single stepped because {dcsr-step} was set. @@ -260,7 +260,7 @@ - Upon entry to debug mode, \RcsrDpc is updated with the virtual address of + Upon entry to debug mode, {csr-dpc} is updated with the virtual address of the next instruction to be executed. The behavior is described in more detail in Table~\ref{tab:dpc}. @@ -281,8 +281,8 @@ \hline trigger module & The address of the next instruction to be executed at the time that debug mode was entered. If the trigger is - \RcsrMcontrol and \FcsrMcontrolTiming is 0 or if the trigger is - \RcsrMcontrolSix and \FcsrMcontrolSixHitOne is 0, this + {csr-mcontrol} and {mcontrol-timing} is 0 or if the trigger is + {csr-mcontrol}Six and {mcontrol-s}ixHitOne is 0, this corresponds to the address of the instruction which caused the trigger to fire. \\ \hline @@ -292,48 +292,48 @@ \end{tabular} \end{table} - Executing the Program Buffer may cause the value of \RcsrDpc to become + Executing the Program Buffer may cause the value of {csr-dpc} to become \unspecified. If that is the case, it must be possible to read/write - \RcsrDpc using an abstract command with \FacAccessregisterPostexec not - set. The debugger must attempt to save \RcsrDpc between halting and - executing a Program Buffer, and then restore \RcsrDpc before leaving + {csr-dpc} using an abstract command with {accessregister-postexec} not + set. The debugger must attempt to save {csr-dpc} between halting and + executing a Program Buffer, and then restore {csr-dpc} before leaving Debug Mode. \begin{commentary} - Allowing \RcsrDpc to become \unspecified\ upon Program Buffer + Allowing {csr-dpc} to become \unspecified\ upon Program Buffer execution allows for direct implementations that don't have a separate PC register, and do need to use the PC when executing the Program Buffer. \end{commentary} - If the Access Register abstract command supports reading \RcsrDpc while + If the Access Register abstract command supports reading {csr-dpc} while the hart is running, then the value read should be the address of a recently executed instruction. - If the Access Register abstract command supports writing \RcsrDpc while + If the Access Register abstract command supports writing {csr-dpc} while the hart is running, then the executing program should jump to the written address shortly after the write occurs. - The writability of \RcsrDpc follows the same rules as \Rmepc as defined - in the Privileged Spec. In particular, \RcsrDpc must be able to hold + The writability of {csr-dpc} follows the same rules as \Rmepc as defined + in the Privileged Spec. In particular, {csr-dpc} must be able to hold all valid virtual addresses and the writability of the low bits depends on IALIGN. When resuming, the hart's PC is updated to the virtual address stored in - \RcsrDpc. A debugger may write \RcsrDpc to change where the hart resumes. + {csr-dpc}. A debugger may write {csr-dpc} to change where the hart resumes. Optional scratch register that can be used by implementations that need - it. A debugger must not write to this register unless \RdmHartinfo + it. A debugger must not write to this register unless {dm-hartinfo} explicitly mentions it (the Debug Module may use this register internally). Optional scratch register that can be used by implementations that need - it. A debugger must not write to this register unless \RdmHartinfo + it. A debugger must not write to this register unless {dm-hartinfo} explicitly mentions it (the Debug Module may use this register internally). diff --git a/xml/dm_registers.xml b/xml/dm_registers.xml index 2b370b2e..f8a5f1fb 100755 --- a/xml/dm_registers.xml +++ b/xml/dm_registers.xml @@ -4,18 +4,18 @@ This register reports status for the overall Debug Module as well as - the currently selected harts, as defined in \FdmDmcontrolHasel. Its address will - not change in the future, because it contains \FdmDmstatusVersion. + the currently selected harts, as defined in {dmcontrol-hasel}. Its address will + not change in the future, because it contains {dmstatus-version}. - Unimplemented, or \FdmDmcontrolNdmreset is zero and no ndmreset is currently + Unimplemented, or {dmcontrol-ndmreset} is zero and no ndmreset is currently in progress. - \FdmDmcontrolNdmreset is currently nonzero, or there is an ndmreset in progress. + {dmcontrol-ndmreset} is currently nonzero, or there is an ndmreset in progress. @@ -25,7 +25,7 @@ The per-hart {\tt unavail} bits are sticky. Once they are set, they will - not clear until the debugger acknowledges them using \FdmDmcontrolAckunavail. + not clear until the debugger acknowledges them using {dmcontrol-ackunavail}. @@ -34,7 +34,7 @@ the debugger from having to write the {\tt ebreak} itself, and allows the Program Buffer to be one word smaller. - This must be 1 when \FdmAbstractcsProgbufsize is 1. + This must be 1 when {abstractcs-progbufsize} is 1. @@ -63,12 +63,12 @@ This field is 1 when all currently selected harts are - unavailable, or (if \FdmDmstatusStickyunavail is 1) were + 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 \FdmDmstatusStickyunavail is 1) was unavailable without + or (if {dmstatus-stickyunavail} is 1) was unavailable without that being acknowledged. @@ -100,30 +100,30 @@ The authentication module is ready to process the next - read/write to \RdmAuthdata. + read/write to {dm-authdata}. - The authentication module is busy. Accessing \RdmAuthdata results + The authentication module is busy. Accessing {dm-authdata} results in unspecified behavior. - \FdmDmstatusAuthbusy only becomes set in immediate response to an access to - \RdmAuthdata. + {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 \FdmDmcontrolSetresethaltreq and \FdmDmcontrolClrresethaltreq bits. + controllable by the {dmcontrol-setresethaltreq} and {dmcontrol-clrresethaltreq} bits. 0 otherwise. - \RdmConfstrptrZero--\RdmConfstrptrThree hold information which + {dm-confstrptr0}--{dm-confstrptr3} hold information which is not relevant to the configuration structure. - \RdmConfstrptrZero--\RdmConfstrptrThree hold the address of the + {dm-confstrptr0}--{dm-confstrptr3} hold the address of the configuration structure. @@ -156,12 +156,12 @@ This register controls the overall Debug Module - as well as the currently selected harts, as defined in \FdmDmcontrolHasel. + as well as the currently selected harts, as defined in {dmcontrol-hasel}. \label{hartsel} \index{hartsel} - Throughout this document we refer to \Fhartsel, which is \FdmDmcontrolHartselhi - combined with \FdmDmcontrolHartsello. While the spec allows for 20 \Fhartsel bits, + Throughout this document we refer to \Fhartsel, which is {dmcontrol-hartselhi} + combined with {dmcontrol-hartsello}. While the spec allows for 20 \Fhartsel bits, an implementation may choose to implement fewer than that. The actual width of \Fhartsel is called {\tt HARTSELLEN}. It must be at least 0 and at most 20. A debugger should discover {\tt HARTSELLEN} by writing @@ -170,20 +170,20 @@ \Fhartsel while an abstract command is executing. \begin{commentary} - There are separate \FdmDmcontrolSetresethaltreq and \FdmDmcontrolClrresethaltreq bits so that - it is possible to write \RdmDmcontrol without changing the halt-on-reset + 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. \end{commentary} On any given write, a debugger may only write 1 to at most one of the - following bits: \FdmDmcontrolResumereq, \FdmDmcontrolHartreset, \FdmDmcontrolAckhavereset, - \FdmDmcontrolSetresethaltreq, and \FdmDmcontrolClrresethaltreq. The others must be written 0. + following bits: {dmcontrol-resumereq}, {dmcontrol-hartreset}, {dmcontrol-ackhavereset}, + {dmcontrol-setresethaltreq}, and {dmcontrol-clrresethaltreq}. The others must be written 0. \label{resethaltreq} \index{resethaltreq} \Fresethaltreq is an optional internal bit of per-hart state that cannot be - read, but can be written with \FdmDmcontrolSetresethaltreq and \FdmDmcontrolClrresethaltreq. + read, but can be written with {dmcontrol-setresethaltreq} and {dmcontrol-clrresethaltreq}. \label{keepalive} \index{keepalive} @@ -192,11 +192,11 @@ 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 \FdmDmcontrolSetkeepalive and - \FdmDmcontrolClrkeepalive. + written through {dmcontrol-setkeepalive} and + {dmcontrol-clrkeepalive}. - For forward compatibility, \FdmDmstatusVersion will always be readable when bit 1 - (\FdmDmcontrolNdmreset) is 0 and bit 0 (\FdmDmcontrolDmactive) is 1. + For forward compatibility, {dmstatus-version} will always be readable when bit 1 + ({dmcontrol-ndmreset}) is 0 and bit 0 ({dmcontrol-dmactive}) is 1. @@ -207,16 +207,16 @@ harts. Running harts will halt whenever their halt request bit is set. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. 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. - \FdmDmcontrolResumereq is ignored if \FdmDmcontrolHaltreq is set. + {dmcontrol-resumereq} is ignored if {dmcontrol-haltreq} is set. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. This optional field writes the reset bit for all the currently @@ -230,7 +230,7 @@ after writing 1 the debugger can read the register back to see if the feature is supported. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. @@ -241,7 +241,7 @@ Clears {\tt havereset} for any selected harts. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. @@ -252,7 +252,7 @@ Clears {\tt unavail} for any selected harts that are currently available. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. Selects the definition of currently selected harts. @@ -282,34 +282,34 @@ This optional field sets \Fkeepalive for all currently selected - harts, unless \FdmDmcontrolClrkeepalive is simultaneously set to + harts, unless {dmcontrol-clrkeepalive} is simultaneously set to 1. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. This optional field clears \Fkeepalive for all currently selected harts. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. This optional field writes the halt-on-reset request bit for all - currently selected harts, unless \FdmDmcontrolClrresethaltreq is + 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 \FdmDmcontrolClrresethaltreq to clear it. + cleared. The debugger must write to {dmcontrol-clrresethaltreq} to clear it. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. - If \FdmDmstatusHasresethaltreq is 0, this field is not implemented. + If {dmstatus-hasresethaltreq} is 0, this field is not implemented. This optional field clears the halt-on-reset request bit for all currently selected harts. - Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + Writes apply to the new value of \Fhartsel and {dmcontrol-hasel}. @@ -324,17 +324,17 @@ This bit serves as a reset signal for the Debug Module itself. After changing the value of this bit, the debugger must poll - \RdmDmcontrol until \FdmDmcontrolDmactive has taken the requested value - before performing any action that assumes the requested \FdmDmcontrolDmactive + {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 \FdmDmcontrolDmactive to the requested value. + indicate completion by setting {dmcontrol-dmactive} to the requested value. The module's state, including authentication mechanism, - takes its reset values (the \FdmDmcontrolDmactive bit is the only bit which can + 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, \FdmDmstatusVersion might not return + to the module may fail. Specifically, {dmstatus-version} might not return correct data. @@ -345,9 +345,9 @@ 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 \FdmDmcontrolDmactive, - poll until \FdmDmcontrolDmactive is observed 0, write 1 to \FdmDmcontrolDmactive, and - poll until \FdmDmcontrolDmactive is observed 1. + To place the Debug Module into a known state, a debugger may 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 @@ -370,7 +370,7 @@ Number of {\tt dscratch} registers available for the debugger - to use during program buffer execution, starting from \RcsrDscratchZero. + to use during program buffer execution, starting from {csr-dscratch0}. The debugger can make no assumptions about the contents of these registers between commands. @@ -388,20 +388,20 @@ - If \FdmHartinfoDataaccess is 0: Number of CSRs dedicated to + If {hartinfo-dataaccess} is 0: Number of CSRs dedicated to shadowing the {\tt data} registers. - If \FdmHartinfoDataaccess is 1: Number of 32-bit words in the memory map + If {hartinfo-dataaccess} is 1: Number of 32-bit words in the memory map dedicated to shadowing the {\tt data} registers. Since there are at most 12 {\tt data} registers, the value in this register must be 12 or smaller. - If \FdmHartinfoDataaccess is 0: The number of the first CSR dedicated to + If {hartinfo-dataaccess} is 0: The number of the first CSR dedicated to shadowing the {\tt data} registers. - If \FdmHartinfoDataaccess is 1: Address of RAM where the data + 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 \Xzero as the address register. @@ -412,7 +412,7 @@ This register selects which of the 32-bit portion of the hart array mask - register (see Section~\ref{hartarraymask}) is accessible in \RdmHawindow. + register (see Section~\ref{hartarraymask}) is accessible in {dm-hawindow}. @@ -425,13 +425,13 @@ This register provides R/W access to a 32-bit portion of the hart array mask register (see Section~\ref{hartarraymask}). - The position of the window is determined by \RdmHawindowsel. I.e. bit 0 - refers to hart $\RdmHawindowsel * 32$, while bit 31 refers to hart - $\RdmHawindowsel * 32 + 31$. + The position of the window is determined by {dm-hawindowsel}. I.e. bit 0 + refers to hart ${dm-hawindowsel} * 32$, while bit 31 refers to hart + ${dm-hawindowsel} * 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 \FdmHawindowselHawindowsel. + of {hawindowsel-hawindowsel}. @@ -439,11 +439,11 @@ Writing this register while an abstract command is executing causes - \FdmAbstractcsCmderr to become 1 (busy) once the command completes + {abstractcs-cmderr} to become 1 (busy) once the command completes (busy becomes 0). \begin{commentary} - \FdmAbstractcsDatacount must be at least 1 to support RV32 harts, 2 to support + {abstractcs-datacount} must be at least 1 to support RV32 harts, 2 to support RV64 harts, or 4 to support RV128 harts. \end{commentary} @@ -461,7 +461,7 @@ An abstract command is currently being executed. - This bit is set as soon as \RdmCommand is written, and is + This bit is set as soon as {dm-command} is written, and is not cleared until that command has completed. @@ -485,21 +485,21 @@ 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 \FdmAbstractcsBusy is 0. + This field only contains a valid value if {abstractcs-busy} is 0. No error. - An abstract command was executing while \RdmCommand, - \RdmAbstractcs, or \RdmAbstractauto was written, or when one + An abstract command was executing while {dm-command}, + {dm-abstractcs}, or {dm-abstractauto} was written, or when one of the {\tt data} or {\tt progbuf} registers was read or written. - This status is only written if \FdmAbstractcsCmderr contains 0. + This status is only written if {abstractcs-cmderr} contains 0. - The command in \RdmCommand is not supported. It + 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. @@ -540,16 +540,16 @@ executed. Writing this register while an abstract command is executing causes - \FdmAbstractcsCmderr to become 1 (busy) once the command completes + {abstractcs-cmderr} to become 1 (busy) once the command completes (busy becomes 0). - If \FdmAbstractcsCmderr is non-zero, writes to this register are ignored. + If {abstractcs-cmderr} is non-zero, writes to this register are ignored. \begin{commentary} - \FdmAbstractcsCmderr inhibits starting a new command to accommodate debuggers + {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 \FdmAbstractcsCmderr in between. They can safely do - so and check \FdmAbstractcsCmderr at the end without worrying that one command + 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. \end{commentary} @@ -575,26 +575,26 @@ If this register is written while an abstract command is executing then the write is ignored and - \FdmAbstractcsCmderr becomes 1 (busy) once the command completes + {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 {\tt progbuf} word cause the DM to act as if the - current value in \RdmCommand was written there again after the + current value in {dm-command} was written there again after the access to {\tt progbuf} completes. When a bit in this field is 1, read or write accesses to the corresponding {\tt data} word cause the DM to act as if the current - value in \RdmCommand was written there again after the + value in {dm-command} was written there again after the access to {\tt data} completes. - When \FdmDmstatusConfstrptrvalid is set, reading this register returns bits 31:0 + When {dmstatus-confstrptrvalid} is set, reading this register returns bits 31:0 of the configuration structure pointer. Reading the other {\tt confstrptr} registers returns the upper bits of the address. @@ -603,7 +603,7 @@ this must be an address that can be used to access the configuration structure from the hart with ID 0. - If \FdmDmstatusConfstrptrvalid is 0, then the {\tt confstrptr} registers + If {dmstatus-confstrptrvalid} is 0, then the {\tt confstrptr} registers hold identifier information which is not further specified in this document. @@ -613,18 +613,18 @@ - When \FdmDmstatusConfstrptrvalid is set, reading this register returns bits 63:32 - of the configuration structure pointer. See \RdmConfstrptrZero for more details. + When {dmstatus-confstrptrvalid} is set, reading this register returns bits 63:32 + of the configuration structure pointer. See {dm-confstrptr0} for more details. - When \FdmDmstatusConfstrptrvalid is set, reading this register returns bits 95:64 - of the configuration structure pointer. See \RdmConfstrptrZero 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 \FdmDmstatusConfstrptrvalid is set, reading this register returns bits 127:96 - of the configuration structure pointer. See \RdmConfstrptrZero 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. @@ -637,16 +637,16 @@ - \RdmDataZero through \RdmDataEleven are registers that may - be read or changed by abstract commands. \FdmAbstractcsDatacount indicates how many - of them are implemented, starting at \RdmDataZero, counting up. + {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. Table~\ref{tab:datareg} shows how abstract commands use these registers. Accessing these registers while an abstract command is executing causes - \FdmAbstractcsCmderr to be set to 1 (busy) if it is 0. + {abstractcs-cmderr} to be set to 1 (busy) if it is 0. - Attempts to write them while \FdmAbstractcsBusy is set does not change their value. + 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 @@ -670,18 +670,18 @@ - \RdmProgbufZero through \RdmProgbufFifteen must provide write access to the + {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. - \FdmAbstractcsProgbufsize indicates how many {\tt progbuf} registers are - implemented starting at \RdmProgbufZero, counting up. + {abstractcs-progbufsize} indicates how many {\tt progbuf} registers are + implemented starting at {dm-progbuf0}, counting up. Accessing these registers while an abstract command is executing causes - \FdmAbstractcsCmderr to be set to 1 (busy) if it is 0. + {abstractcs-cmderr} to be set to 1 (busy) if it is 0. - Attempts to write them while \FdmAbstractcsBusy is set does not change their value. + Attempts to write them while {abstractcs-busy} is set does not change their value. @@ -707,7 +707,7 @@ This register serves as a 32-bit serial port to/from the authentication module. - When \FdmDmstatusAuthbusy is clear, the debugger can communicate with the + 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. @@ -716,12 +716,12 @@ This register contains DM control and status bits that didn't easily - fit in \RdmDmcontrol and \RdmDmstatus. All are optional. + fit in {dm-dmcontrol} and {dm-dmstatus}. All are optional. - If halt groups are not implemented, then \FdmDmcsTwoGroup will always - be 0 when \FdmDmcsTwoGrouptype is 0. + 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 \FdmDmcsTwoGrouptype will + 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 @@ -744,13 +744,13 @@ change it to a valid one or 0 if no DM external triggers exist. - When \FdmDmcsTwoHgselect is 0, contains the group of the hart + When {dmcs2-hgselect} is 0, contains the group of the hart specified by \Fhartsel. - When \FdmDmcsTwoHgselect is 1, contains the group of the DM external - trigger selected by \FdmDmcsTwoDmexttrigger. + 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 \FdmDmcsTwoHgwrite + 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 @@ -761,16 +761,16 @@ If groups aren't implemented, then this entire field is 0. - When 1 is written and \FdmDmcsTwoHgselect is 0, for every selected - hart the DM will change its group to the value written to \FdmDmcsTwoGroup, + 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 \FdmDmcsTwoHgselect is 1, the DM will change - the group of the DM external trigger selected by \FdmDmcsTwoDmexttrigger - to the value written to \FdmDmcsTwoGroup, if the hardware supports + 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. @@ -867,7 +867,7 @@ 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 \FdmSbcsSbbusy is set). It remains set until + 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 @@ -879,12 +879,12 @@ 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 \RdmSbcs while \FdmSbcsSbbusy is high result in undefined - behavior. A debugger must not write to \RdmSbcs until it reads - \FdmSbcsSbbusy as 0. + 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 \RdmSbaddressZero automatically triggers a + When 1, every write to {dm-sbaddress0} automatically triggers a system bus read at the new address. @@ -910,15 +910,15 @@ 128-bit - If \FdmSbcsSbaccess has an unsupported value when the DM starts a bus - access, the access is not performed and \FdmSbcsSberror is set to 4. + 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, {\tt sbaddress} is incremented by the access size (in - bytes) selected in \FdmSbcsSbaccess after every system bus access. + bytes) selected in {sbcs-sbaccess} after every system bus access. - When 1, every read from \RdmSbdataZero automatically triggers a + When 1, every read from {dm-sbdata0} automatically triggers a system bus read at the (possibly auto-incremented) address. @@ -976,18 +976,18 @@ - If \FdmSbcsSbasize is 0, then this register is not present. + If {sbcs-sbasize} is 0, then this register is not present. When the system bus manager is busy, writes to this register will set - \FdmSbcsSbbusyerror and don't do anything else. + {sbcs-sbbusyerror} and don't do anything else. - \begin{steps}{If \FdmSbcsSberror is 0, \FdmSbcsSbbusyerror is 0, and \FdmSbcsSbreadonaddr + \begin{steps}{If {sbcs-sberror} is 0, {sbcs-sbbusyerror} is 0, and {sbcs-sbreadonaddr} is set then writes to this register start the following:} - \item Set \FdmSbcsSbbusy. + \item Set {sbcs-sbbusy}. \item Perform a bus read from the new value of {\tt sbaddress}. - \item If the read succeeded and \FdmSbcsSbautoincrement is set, increment + \item If the read succeeded and {sbcs-sbautoincrement} is set, increment {\tt sbaddress}. - \item Clear \FdmSbcsSbbusy. + \item Clear {sbcs-sbbusy}. \end{steps} @@ -996,10 +996,10 @@ - If \FdmSbcsSbasize is less than 33, then this register is not present. + 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 - \FdmSbcsSbbusyerror and don't do anything else. + {sbcs-sbbusyerror} and don't do anything else. Accesses bits 63:32 of the physical address in {\tt sbaddress} (if @@ -1008,10 +1008,10 @@ - If \FdmSbcsSbasize is less than 65, then this register is not present. + 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 - \FdmSbcsSbbusyerror and don't do anything else. + {sbcs-sbbusyerror} and don't do anything else. Accesses bits 95:64 of the physical address in {\tt sbaddress} (if @@ -1020,10 +1020,10 @@ - If \FdmSbcsSbasize is less than 97, then this register is not present. + 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 - \FdmSbcsSbbusyerror and don't do anything else. + {sbcs-sbbusyerror} and don't do anything else. Accesses bits 127:96 of the physical address in {\tt sbaddress} (if @@ -1032,41 +1032,41 @@ - If all of the {\tt sbaccess} bits in \RdmSbcs are 0, then this register + If all of the {\tt sbaccess} bits in {dm-sbcs} are 0, then this register is not present. Any successful system bus read updates {\tt sbdata}. If the width of the read access is less than the width of {\tt sbdata}, the contents of the remaining high bits may take on any value. - If either \FdmSbcsSberror or \FdmSbcsSbbusyerror isn't 0 then accesses do nothing. + If either {sbcs-sberror} or {sbcs-sbbusyerror} isn't 0 then accesses do nothing. - If the bus manager is busy then accesses set \FdmSbcsSbbusyerror, and don't do + If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. \begin{steps}{Writes to this register start the following:} - \item Set \FdmSbcsSbbusy. + \item Set {sbcs-sbbusy}. \item Perform a bus write of the new value of {\tt sbdata} to {\tt sbaddress}. - \item If the write succeeded and \FdmSbcsSbautoincrement is set, + \item If the write succeeded and {sbcs-sbautoincrement} is set, increment {\tt sbaddress}. - \item Clear \FdmSbcsSbbusy. + \item Clear {sbcs-sbbusy}. \end{steps} \begin{steps}{Reads from this register start the following:} \item ``Return'' the data. - \item Set \FdmSbcsSbbusy. - \item \begin{steps}{If \FdmSbcsSbreadondata is set:} + \item Set {sbcs-sbbusy}. + \item \begin{steps}{If {sbcs-sbreadondata} is set:} \item Perform a system bus read from the address contained in {\tt sbaddress}, placing the result in {\tt sbdata}. - \item If \FdmSbcsSbautoincrement is set and the read was + \item If {sbcs-sbautoincrement} is set and the read was successful, increment {\tt sbaddress}. \end{steps} - \item Clear \FdmSbcsSbbusy. + \item Clear {sbcs-sbbusy}. \end{steps} - Only \RdmSbdataZero has this behavior. The other {\tt sbdata} registers + Only {dm-sbdata0} has this behavior. The other {\tt sbdata} registers have no side effects. On systems that have buses wider than 32 bits, a - debugger should access \RdmSbdataZero after accessing the other {\tt + debugger should access {dm-sbdata0} after accessing the other {\tt sbdata} registers. @@ -1075,10 +1075,10 @@ - If \FdmSbcsSbaccessSixtyfour and \FdmSbcsSbaccessOneTwentyeight are 0, then this + If {sbcs-sbaccess}Sixtyfour and {sbcs-sbaccess}OneTwentyeight are 0, then this register is not present. - If the bus manager is busy then accesses set \FdmSbcsSbbusyerror, and don't do + If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. @@ -1088,9 +1088,9 @@ - This register only exists if \FdmSbcsSbaccessOneTwentyeight is 1. + This register only exists if {sbcs-sbaccess}OneTwentyeight is 1. - If the bus manager is busy then accesses set \FdmSbcsSbbusyerror, and don't do + If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. @@ -1100,9 +1100,9 @@ - This register only exists if \FdmSbcsSbaccessOneTwentyeight is 1. + This register only exists if {sbcs-sbaccess}OneTwentyeight is 1. - If the bus manager is busy then accesses set \FdmSbcsSbbusyerror, and don't do + If the bus manager is busy then accesses set {sbcs-sbbusyerror}, and don't do anything else. @@ -1117,7 +1117,7 @@ - The optional \RdmCustomZero through \RdmCustomFifteen registers may + The optional {dm-custom}Zero through {dm-custom}Fifteen registers may be used for non-standard features. Future versions of the debug spec will not use these addresses. diff --git a/xml/hwbp_registers.xml b/xml/hwbp_registers.xml index 99b7755a..07786d55 100755 --- a/xml/hwbp_registers.xml +++ b/xml/hwbp_registers.xml @@ -1,5 +1,5 @@ - The Trigger Module registers, except \RcsrMscontext, \RcsrScontext, and \RcsrHcontext, are only accessible in machine + The Trigger Module registers, except {csr-mscontext}, {csr-scontext}, and {csr-hcontext}, are only accessible in machine and Debug Mode to prevent untrusted user code from causing entry into Debug Mode without the OS's permission. @@ -7,9 +7,9 @@ Mode. On systems where those values of XLEN can differ, this is handled as follows. Fields retain their values regardless of XLEN, which only affects where - in the register these fields appear (e.g. \FcsrTdataOneType). Some fields + in the register these fields appear (e.g. {tdata1-type}). Some fields are wider when XLEN is 64 than when it is 32 (e.g. - \FcsrTextraThirtytwoSvalue). The high bits in such fields retain their + {textra32-svalue}). The high bits in such fields retain their value but are not readable when XLEN is 32. A modification of a register when XLEN is 32 clears any inaccessible bits in that register. @@ -22,10 +22,10 @@ This register is \warl. Writes of values greater than or equal to the number of supported triggers may result in a different value in this register than what was - written or may point to a trigger where \FcsrTdataOneType=0. + written or may point to a trigger where {tdata1-type}=0. To verify that what they wrote is a valid index, debuggers can - read back the value and check that \RcsrTselect holds what they wrote - and read \RcsrTdataOne to see that \FcsrTdataOneType is non-zero. + read back the value and check that {csr-tselect} holds what they wrote + and read {csr-tdata1} to see that {tdata1-type} is non-zero. Since triggers can be used both by Debug Mode and M-mode, the external debugger must restore this register if it modifies it. @@ -34,18 +34,18 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. This register is optional if no triggers are implemented. Writing 0 to this register must result in a trigger that is disabled. If this trigger supports multiple types, then the hardware should - disable it by changing \FcsrTdataOneType to 15. + disable it by changing {tdata1-type} to 15. - There is no trigger at this \RcsrTselect. + There is no trigger at this {csr-tselect}. @@ -55,34 +55,34 @@ The trigger is an address/data match trigger. The remaining bits - in this register act as described in \RcsrMcontrol. + in this register act as described in {csr-mcontrol}. The trigger is an instruction count trigger. The remaining bits - in this register act as described in \RcsrIcount. + in this register act as described in {csr-icount}. The trigger is an interrupt trigger. The remaining bits - in this register act as described in \RcsrItrigger. + in this register act as described in {csr-itrigger}. The trigger is an exception trigger. The remaining bits - in this register act as described in \RcsrEtrigger. + in this register act as described in {csr-etrigger}. The trigger is an address/data match trigger. The remaining bits - in this register act as described in \RcsrMcontrolSix. This is similar + in this register act as described in {csr-mcontrol}Six. This is similar to a type 2 trigger, but provides additional functionality and should be used instead of type 2 in newer implementations. The trigger is a trigger source external to the TM. The - remaining bits in this register act as described in \RcsrTmexttrigger. + remaining bits in this register act as described in {csr-tmexttrigger}. @@ -90,10 +90,10 @@ - This trigger is disabled. In this state, \RcsrTdataTwo and - \RcsrTdataThree can be written with any value that is supported for + This trigger is disabled. In this state, {csr-tdata2} and + {csr-tdata3} can be written with any value that is supported for any of the types this trigger implements. - The remaining bits in this register, except for \FcsrTdataOneDmode, + The remaining bits in this register, except for {tdata1-dmode}, are ignored. @@ -101,34 +101,34 @@ - If \FcsrTdataOneType is 0, then this bit is hard-wired to 0. + If {tdata1-type} is 0, then this bit is hard-wired to 0. Both Debug and M-mode can write the {\tt tdata} registers at the - selected \RcsrTselect. + selected {csr-tselect}. Only Debug Mode can write the {\tt tdata} registers at the - selected \RcsrTselect. Writes from other modes are ignored. + selected {csr-tselect}. Writes from other modes are ignored. This bit is only writable from Debug Mode. In ordinary use, external debuggers will always set this bit when configuring a trigger. When clearing this bit, debuggers should also set the action field - (whose location depends on \FcsrTdataOneType) to something other + (whose location depends on {tdata1-type}) to something other than 1. - If \FcsrTdataOneType is 0, then this field is hard-wired to 0. + If {tdata1-type} is 0, then this field is hard-wired to 0. Trigger-specific data. - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. Trigger-specific data. It is optional if no implemented triggers use @@ -142,7 +142,7 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. Trigger-specific data. It is optional if no implemented triggers use @@ -156,13 +156,13 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. This register is optional if no triggers are implemented, or if - \FcsrTdataOneType is not writable and \FcsrTinfoVersion would be 0. In + {tdata1-type} is not writable and {tinfo-version} would be 0. In this case the debugger can read the only supported type from - \RcsrTdataOne. + {csr-tdata1}. @@ -172,11 +172,11 @@ made on February 2, 2023. \begin{steps}{In these older versions:} - \item \RcsrMcontrolSix has a timing bit identical to - \FcsrMcontrolTiming - \item \FcsrMcontrolSixHitZero behaves just as \FcsrMcontrolHit. - \item \FcsrMcontrolSixHitOne is read-only 0. - \item Encodings for \FcsrMcontrolSixSize for access sizes larger + \item {csr-mcontrol}Six has a timing bit identical to + {mcontrol-timing} + \item {mcontrol-s}ixHitZero behaves just as {mcontrol-hit}. + \item {mcontrol-s}ixHitOne is read-only 0. + \item Encodings for {mcontrol-s}ixSize for access sizes larger than 64 bits are different. \end{steps} @@ -187,7 +187,7 @@ - One bit for each possible \FcsrTdataOneType enumerated in \RcsrTdataOne. Bit N + One bit for each possible {tdata1-type} enumerated in {csr-tdata1}. Bit N corresponds to type N. If the bit is set, then that type is supported by the currently selected trigger. @@ -204,12 +204,12 @@ M-mode previous trigger enable field. - \FcsrTcontrolMpte and \FcsrTcontrolMte provide one solution to a problem + {tcontrol-mpte} and {tcontrol-mte} provide one solution to a problem regarding triggers with action=0 firing in M-mode trap handlers. See Section~\ref{sec:nativetrigger} for more details. - When any trap into M-mode is taken, \FcsrTcontrolMpte is set to the value of - \FcsrTcontrolMte. + When any trap into M-mode is taken, {tcontrol-mpte} is set to the value of + {tcontrol-mte}. @@ -223,22 +223,22 @@ Triggers do match/fire while the hart is in M-mode. - When any trap into M-mode is taken, \FcsrTcontrolMte is set to 0. When {\tt - mret} is executed, \FcsrTcontrolMte is set to the value of \FcsrTcontrolMpte. + When any trap into M-mode is taken, {tcontrol-mte} is set to 0. When {\tt + mret} is executed, {tcontrol-mte} is set to the value of {tcontrol-mpte}. This optional register may be implemented only if the H extension is - implemented. If it is implemented, \RcsrMcontext must also be implemented. + implemented. If it is implemented, {csr-mcontext} must also be implemented. This register is only accessible in HS-Mode, M-mode and Debug Mode. If Smstateen is implemented, then accessibility of in HS-Mode is controlled by \Rmstateenzero[57]. - This register is an alias of the \RcsrMcontext register, providing - access to the \FcsrMcontextHcontext field from HS-Mode. + This register is an alias of the {csr-mcontext} register, providing + access to the {mcontext-hcontext} field from HS-Mode. @@ -246,9 +246,9 @@ M-mode and Debug Mode. Accessibility of this CSR is controlled by \Rmstateenzero[57] and - \Rhstateenzero[57] in the Smstateen extension. Enabling \RcsrScontext + \Rhstateenzero[57] in the Smstateen extension. Enabling {csr-scontext} can be a security risk in a virtualized system with a hypervisor that - does not swap \RcsrScontext. + does not swap {csr-scontext}. Supervisor mode software can write a context number to this register, which can be used to set triggers that only fire in that @@ -261,32 +261,32 @@ - This register must be implemented if \RcsrHcontext is implemented, and + This register must be implemented if {csr-hcontext} is implemented, and is optional otherwise. It is only accessible in M-mode and Debug mode. \begin{commentary} - \FcsrMcontextHcontext is primarily useful to set triggers on + {mcontext-hcontext} is primarily useful to set triggers on hypervisor systems that only fire when a given VM is executing. It is also useful in systems where M-Mode implements something like a hypervisor directly. \end{commentary} - M-Mode or HS-Mode (using \RcsrHcontext) software can write a context + M-Mode or HS-Mode (using {csr-hcontext}) software can write a context number to this register, which can be used to set triggers that only fire in that specific context. An implementation may tie any number of upper bits in this field to 0. If the H extension is not implemented, it's recommended to implement no more than 6 bits on RV32 and 13 on RV64 (as visible through the - \RcsrMcontext register). If the H extension is implemented, + {csr-mcontext} register). If the H extension is implemented, it's recommended to implement no more than 7 bits on RV32 and 14 on RV64. - This optional register is an alias for \RcsrScontext. It is only + This optional register is an alias for {csr-scontext}. It is only accessible in S/HS-mode, M-mode and Debug Mode. It is included for backward compatibility with version 0.13. @@ -294,33 +294,33 @@ The encoding of this CSR does not conform to the CSR Address Mapping Convention in the Privileged Spec. It is expected that new implementations will not support this encoding and that new - debuggers will not use this CSR if \RcsrScontext is available. + debuggers will not use this CSR if {csr-scontext} is available. \end{commentary} - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 2. + This register is accessible as {csr-tdata1} when {tdata1-type} is 2. This trigger type is deprecated. It is included for backward compatibility with version 0.13. \begin{commentary} This trigger type only supports a subset of features of the newer - \RcsrMcontrolSix. It is expected that new implementations will not + {csr-mcontrol}Six. It is expected that new implementations will not support this trigger type and that new debuggers will not use it if - \RcsrMcontrolSix is available. + {csr-mcontrol}Six is available. \end{commentary} Address and data trigger implementation are heavily dependent on how the processor core is implemented. To accommodate various implementations, execute, load, and store address/data triggers may fire at whatever point in time is most convenient for the implementation. - The debugger may request specific timings as described in \FcsrMcontrolTiming. + The debugger may request specific timings as described in {mcontrol-timing}. Table~\ref{tab:hwbp_timing} suggests timings for the best user experience. - A chain of triggers that don't all have the same \FcsrMcontrolTiming + A chain of triggers that don't all have the same {mcontrol-timing} value will never fire. That means to implement the suggestions in Table~\ref{tab:hwbp_timing}, both timings should be supported on load address triggers. @@ -328,22 +328,22 @@ The Privileged Spec says that breakpoint exceptions that occur on instruction fetches, loads, or stores update the {\tt tval} CSR with either zero or the faulting virtual address. The faulting - virtual address for an mcontrol trigger with \FcsrMcontrolAction=0 is the + virtual address for an mcontrol trigger with {mcontrol-action}=0 is the address being accessed and which caused that trigger to fire. If multiple mcontrol triggers are chained then the faulting virtual address is the address which caused any of the chained triggers to fire. - If \RcsrTextraThirtytwo or \RcsrTextraSixtyfour are implemented for this + If {csr-textra32} or {csr-textra64} are implemented for this trigger, it only matches when the conditions set there are satisfied. Specifies the largest naturally aligned powers-of-two (NAPOT) range - supported by the hardware when \FcsrMcontrolMatch is 1. The value is the + supported by the hardware when {mcontrol-match} is 1. The value is the logarithm base 2 of the number of bytes in that range. - A value of 0 indicates \FcsrMcontrolMatch 1 is not supported. + A value of 0 indicates {mcontrol-match} 1 is not supported. A value of 63 corresponds to the maximum NAPOT range, which is $2^{63}$ bytes in size. @@ -351,7 +351,7 @@ This field only exists when XLEN is at least 64. It contains the 2 high bits of the access size. The low bits - come from \FcsrMcontrolSizelo. See \FcsrMcontrolSizelo for how this + come from {mcontrol-sizelo}. See {mcontrol-sizelo} for how this is used. @@ -384,12 +384,12 @@ The action for this trigger will be taken just before the instruction that triggered it is retired, but after all preceding - instructions are retired. \Rxepc or \RcsrDpc (depending - on \FcsrMcontrolAction) must be set to the virtual address of the + instructions are retired. \Rxepc or {csr-dpc} (depending + on {mcontrol-action}) must be set to the virtual address of the instruction that matched. - If this is combined with \FcsrMcontrolLoad and - \FcsrMcontrolSelect=1 then a memory access will be + If this is combined with {mcontrol-load} and + {mcontrol-select}=1 then a memory access will be performed (including any side effects of performing such an access) even though the load will not update its destination register. Debuggers should consider this when setting such breakpoints on, for example, @@ -405,30 +405,30 @@ that triggered it is retired. It should be taken before the next instruction is retired, but it is better to implement triggers imprecisely than to not implement them at all. \Rxepc or - \RcsrDpc (depending on \FcsrMcontrolAction) must be set to + {csr-dpc} (depending on {mcontrol-action}) must be set to the virtual address of the next instruction that must be executed to preserve the program flow. Most hardware will only implement one timing or the other, possibly - dependent on \FcsrMcontrolSelect, \FcsrMcontrolExecute, - \FcsrMcontrolLoad, and \FcsrMcontrolStore. This bit + dependent on {mcontrol-select}, {mcontrol-execute}, + {mcontrol-load}, and {mcontrol-s}tore. This bit primarily exists for the hardware to communicate to the debugger what will happen. Hardware may implement the bit fully writable, in which case the debugger has a little more control. - Data load triggers with \FcsrMcontrolTiming of 0 will result in the same load + Data load triggers with {mcontrol-timing} of 0 will result in the same load happening again when the debugger lets the hart run. For data load triggers, debuggers must first attempt to set the breakpoint with - \FcsrMcontrolTiming of 1. + {mcontrol-timing} of 1. - If a trigger with \FcsrMcontrolTiming of 0 matches, it is + If a trigger with {mcontrol-timing} of 0 matches, it is implementation-dependent whether that prevents a trigger with - \FcsrMcontrolTiming of 1 matching as well. + {mcontrol-timing} of 1 matching as well. This field contains the 2 low bits of the access size. The high bits come - from \FcsrMcontrolSizehi. The combined value is interpreted as follows: + from {mcontrol-sizehi}. The combined value is interpreted as follows: The trigger will attempt to match against an access of any size. @@ -478,17 +478,17 @@ An implementation must support the value of 0, but all other values are optional. When an implementation supports address triggers - (\FcsrMcontrolSelect=0), it is recommended that those triggers + ({mcontrol-select}=0), it is recommended that those triggers support every access size that the hart supports, as well as for every instruction size that the hart supports. Implementations such as RV32D or RV64V are able to perform loads and stores that are wider than XLEN. Custom extensions may also support instructions that are wider than XLEN. Because - \RcsrTdataTwo is of size XLEN, there is a known limitation that - data value triggers (\FcsrMcontrolSelect=1) can only be supported + {csr-tdata2} is of size XLEN, there is a known limitation that + data value triggers ({mcontrol-select}=1) can only be supported for access sizes up to XLEN bits. When an implementation supports - data value triggers (\FcsrMcontrolSelect=1), it is recommended + data value triggers ({mcontrol-select}=1), it is recommended that those triggers support every access size up to XLEN that the hart supports, as well as for every instruction length up to XLEN that the hart supports. @@ -526,80 +526,80 @@ Debuggers should not terminate a chain with a trigger with a different type. It is undefined when exactly such a chain fires. - Because \FcsrMcontrolChain affects the next trigger, hardware must zero it in - writes to \RcsrMcontrol that set \FcsrTdataOneDmode to 0 if the next trigger has - \FcsrTdataOneDmode of 1. - In addition hardware should ignore writes to \RcsrMcontrol that set - \FcsrTdataOneDmode to 1 if the previous trigger has both \FcsrTdataOneDmode of 0 and - \FcsrMcontrolChain of 1. Debuggers must avoid the latter case by checking - \FcsrMcontrolChain on the previous trigger if they're writing \RcsrMcontrol. + Because {mcontrol-chain} affects the next trigger, hardware must zero it in + writes to {csr-mcontrol} that set {tdata1-dmode} to 0 if the next trigger has + {tdata1-dmode} of 1. + In addition hardware should ignore writes to {csr-mcontrol} that set + {tdata1-dmode} to 1 if the previous trigger has both {tdata1-dmode} of 0 and + {mcontrol-chain} of 1. Debuggers must avoid the latter case by checking + {mcontrol-chain} on the previous trigger if they're writing {csr-mcontrol}. Implementations that wish to limit the maximum length of a trigger chain (eg. to meet timing requirements) may do so by zeroing - \FcsrMcontrolChain in writes to \RcsrMcontrol that would make the chain too long. + {mcontrol-chain} in writes to {csr-mcontrol} that would make the chain too long. - Matches when any compare value equals \RcsrTdataTwo. + Matches when any compare value equals {csr-tdata2}. Matches when the top $M$ bits of any compare value match the top - $M$ bits of \RcsrTdataTwo. + $M$ bits of {csr-tdata2}. $M$ is $|XLEN|-1$ minus the index of the least-significant - bit containing 0 in \RcsrTdataTwo. Debuggers should only write values - to \RcsrTdataTwo such that $M + $\FcsrMcontrolMaskmax$ \geq |XLEN|$ + bit containing 0 in {csr-tdata2}. Debuggers should only write values + to {csr-tdata2} such that $M + ${mcontrol-maskmax}$ \geq |XLEN|$ and $M\gt0$ , otherwise it's undefined on what conditions the trigger will match. Matches when any compare value is greater than (unsigned) or - equal to \RcsrTdataTwo. + equal to {csr-tdata2}. Matches when any compare value is less than (unsigned) - \RcsrTdataTwo. + {csr-tdata2}. Matches when $\frac{|XLEN|}{2}-1$:$0$ of any compare value - equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after + equals $\frac{|XLEN|}{2}-1$:$0$ of {csr-tdata2} after $\frac{|XLEN|}{2}-1$:$0$ of the compare value is ANDed with - $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + $|XLEN|-1$:$\frac{|XLEN|}{2}$ of {csr-tdata2}. Matches when $|XLEN|-1$:$\frac{|XLEN|}{2}$ of any compare - value equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after + value equals $\frac{|XLEN|}{2}-1$:$0$ of {csr-tdata2} after $|XLEN|-1$:$\frac{|XLEN|}{2}$ of the compare value is ANDed with - $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + $|XLEN|-1$:$\frac{|XLEN|}{2}$ of {csr-tdata2}. - Matches when \FcsrMcontrolMatch$=0$ would not match. + Matches when {mcontrol-match}$=0$ would not match. - Matches when \FcsrMcontrolMatch$=1$ would not match. + Matches when {mcontrol-match}$=1$ would not match. - Matches when \FcsrMcontrolMatch$=4$ would not match. + Matches when {mcontrol-match}$=4$ would not match. - Matches when \FcsrMcontrolMatch$=5$ would not match. + Matches when {mcontrol-match}$=5$ would not match. Other values are reserved for future use. All comparisons only look at the lower XLEN (in the current mode) - bits of the compare values and of \RcsrTdataTwo. - When \FcsrMcontrolSelect=1 and access size is N, this is further + bits of the compare values and of {csr-tdata2}. + When {mcontrol-select}=1 and access size is N, this is further reduced, and comparisons only look at the lower N bits of the - compare values and of \RcsrTdataTwo. + compare values and of {csr-tdata2}. When set, enable this trigger in M-mode. @@ -630,13 +630,13 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 6. + This register is accessible as {csr-tdata1} when {tdata1-type} is 6. Implementing this trigger as described here requires that - \FcsrTinfoVersion is 1 or higher, which in turn means \RcsrTinfo must + {tinfo-version} is 1 or higher, which in turn means {csr-tinfo} must be implemented. This replaces mcontrol in newer implementations and serves to provide additional @@ -682,27 +682,27 @@ The Privileged Spec says that breakpoint exceptions that occur on instruction fetches, loads, or stores update the {\tt tval} CSR with either zero or the faulting virtual address. The faulting - virtual address for an mcontrol6 trigger with \FcsrMcontrolSixAction=0 is the + virtual address for an mcontrol6 trigger with {mcontrol-s}ixAction=0 is the address being accessed and which caused that trigger to fire. If multiple mcontrol6 triggers are chained then the faulting virtual address is the address which caused any of the chained triggers to fire. - \begin{steps}{In implementations that support \FcsrMcontrolSixMatch mode 1 (NAPOT), not all + \begin{steps}{In implementations that support {mcontrol-s}ixMatch mode 1 (NAPOT), not all NAPOT ranges may be supported. All NAPOT ranges between $2^{1}$ and $2^{maskmax6}$ are supported where maskmax6 $\geq$ 1. The value of maskmax6 can be determined by the debugger via the following sequence:} - \item Set \FcsrMcontrolSixMatch=1. - \item Read \FcsrMcontrolSixMatch. If it is not 1 then NAPOT matching is not supported. - \item Write all ones to \RcsrTdataTwo. - \item Read \RcsrTdataTwo. The value of maskmax6 is the index of the most significant 0 bit plus 1. + \item Set {mcontrol-s}ixMatch=1. + \item Read {mcontrol-s}ixMatch. If it is not 1 then NAPOT matching is not supported. + \item Write all ones to {csr-tdata2}. + \item Read {csr-tdata2}. The value of maskmax6 is the index of the most significant 0 bit plus 1. \end{steps} - If \RcsrTextraThirtytwo or \RcsrTextraSixtyfour are implemented for this + If {csr-textra32} or {csr-textra64} are implemented for this trigger, it only matches when the conditions set there are satisfied. \begin{commentary} - \FcsrMcontrolSixUncertain and \FcsrMcontrolSixUncertainen exist to + {mcontrol-s}ixUncertain and {mcontrol-s}ixUncertainen exist to accommodate systems where not every memory access is fully observed by the Trigger Module. Possible examples include data values in far AMOs, and the address/data/size of accesses by instructions that perform @@ -744,8 +744,8 @@ virtualization mode. - If they are implemented, \FcsrMcontrolSixHitOne (MSB) and - \FcsrMcontrolSixHitZero (LSB) combine into a single 2-bit field. + If they are implemented, {mcontrol-s}ixHitOne (MSB) and + {mcontrol-s}ixHitZero (LSB) combine into a single 2-bit field. The TM updates this field when the trigger fires. After the debugger has seen the update, it will normally write 0 to this field to so it can see future changes. @@ -763,14 +763,14 @@ explicitly allows for instructions to be partially executed, as described in Section \ref{sec:multistate}. - \Rxepc or \RcsrDpc (depending on \FcsrMcontrolSixAction) must be set + \Rxepc or {csr-dpc} (depending on {mcontrol-s}ixAction) must be set to the virtual address of the instruction that matched. The trigger fired after the instruction that triggered and at least one additional instruction were retired. - \Rxepc or \RcsrDpc (depending on \FcsrMcontrolSixAction) must be set + \Rxepc or {csr-dpc} (depending on {mcontrol-s}ixAction) must be set to the virtual address of the next instruction that must be executed to preserve the program flow. @@ -778,7 +778,7 @@ The trigger fired just after the instruction that triggered it was retired, but before any subsequent instructions were executed. - \Rxepc or \RcsrDpc (depending on \FcsrMcontrolSixAction) must be set + \Rxepc or {csr-dpc} (depending on {mcontrol-s}ixAction) must be set to the virtual address of the next instruction that must be executed to preserve the program flow. @@ -842,17 +842,17 @@ An implementation must support the value of 0, but all other values are optional. When an implementation supports address triggers - (\FcsrMcontrolSixSelect=0), it is recommended that those triggers + ({mcontrol-s}ixSelect=0), it is recommended that those triggers support every access size that the hart supports, as well as for every instruction size that the hart supports. Implementations such as RV32D or RV64V are able to perform loads and stores that are wider than XLEN. Custom extensions may also support instructions that are wider than XLEN. Because - \RcsrTdataTwo is of size XLEN, there is a known limitation that - data value triggers (\FcsrMcontrolSixSelect=1) can only be supported + {csr-tdata2} is of size XLEN, there is a known limitation that + data value triggers ({mcontrol-s}ixSelect=1) can only be supported for access sizes up to XLEN bits. When an implementation supports - data value triggers (\FcsrMcontrolSixSelect=1), it is recommended + data value triggers ({mcontrol-s}ixSelect=1), it is recommended that those triggers support every access size up to XLEN that the hart supports, as well as for every instruction length up to XLEN that the hart supports. @@ -890,82 +890,82 @@ Debuggers should not terminate a chain with a trigger with a different type. It is undefined when exactly such a chain fires. - Because \FcsrMcontrolSixChain affects the next trigger, hardware must zero it in - writes to \RcsrMcontrolSix that set \FcsrTdataOneDmode to 0 if the next trigger has - \FcsrTdataOneDmode of 1. - In addition hardware should ignore writes to \RcsrMcontrolSix that set - \FcsrTdataOneDmode to 1 if the previous trigger has both \FcsrTdataOneDmode of 0 and - \FcsrMcontrolSixChain of 1. Debuggers must avoid the latter case by checking - \FcsrMcontrolSixChain on the previous trigger if they're writing \RcsrMcontrolSix. + Because {mcontrol-s}ixChain affects the next trigger, hardware must zero it in + writes to {csr-mcontrol}Six that set {tdata1-dmode} to 0 if the next trigger has + {tdata1-dmode} of 1. + In addition hardware should ignore writes to {csr-mcontrol}Six that set + {tdata1-dmode} to 1 if the previous trigger has both {tdata1-dmode} of 0 and + {mcontrol-s}ixChain of 1. Debuggers must avoid the latter case by checking + {mcontrol-s}ixChain on the previous trigger if they're writing {csr-mcontrol}Six. Implementations that wish to limit the maximum length of a trigger chain (eg. to meet timing requirements) may do so by zeroing - \FcsrMcontrolSixChain in writes to \RcsrMcontrolSix that would make the chain too long. + {mcontrol-s}ixChain in writes to {csr-mcontrol}Six that would make the chain too long. - Matches when any compare value equals \RcsrTdataTwo. + Matches when any compare value equals {csr-tdata2}. Matches when the top $M$ bits of any compare value match the top - $M$ bits of \RcsrTdataTwo. + $M$ bits of {csr-tdata2}. $M$ is $|XLEN|-1$ minus the index of the least-significant bit - containing 0 in \RcsrTdataTwo. - \RcsrTdataTwo is WARL and if bits $|maskmax6|-1$:0 are written with all + containing 0 in {csr-tdata2}. + {csr-tdata2} is WARL and if bits $|maskmax6|-1$:0 are written with all ones then bit $|maskmax6|-1$ will be set to 0 while the values of bits $|maskmax6|-2$:0 are \unspecified. - Legal values for \RcsrTdataTwo require $M + |maskmax6| \geq |XLEN|$ and $M\gt0$. + Legal values for {csr-tdata2} require $M + |maskmax6| \geq |XLEN|$ and $M\gt0$. See above for how to determine maskmax6. Matches when any compare value is greater than (unsigned) or - equal to \RcsrTdataTwo. + equal to {csr-tdata2}. Matches when any compare value is less than (unsigned) - \RcsrTdataTwo. + {csr-tdata2}. Matches when $\frac{|XLEN|}{2}-1$:$0$ of any compare value - equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after + equals $\frac{|XLEN|}{2}-1$:$0$ of {csr-tdata2} after $\frac{|XLEN|}{2}-1$:$0$ of the compare value is ANDed with - $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + $|XLEN|-1$:$\frac{|XLEN|}{2}$ of {csr-tdata2}. Matches when $|XLEN|-1$:$\frac{|XLEN|}{2}$ of any compare - value equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after + value equals $\frac{|XLEN|}{2}-1$:$0$ of {csr-tdata2} after $|XLEN|-1$:$\frac{|XLEN|}{2}$ of the compare value is ANDed with - $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + $|XLEN|-1$:$\frac{|XLEN|}{2}$ of {csr-tdata2}. - Matches when \FcsrMcontrolSixMatch$=0$ would not match. + Matches when {mcontrol-s}ixMatch$=0$ would not match. - Matches when \FcsrMcontrolSixMatch$=1$ would not match. + Matches when {mcontrol-s}ixMatch$=1$ would not match. - Matches when \FcsrMcontrolSixMatch$=4$ would not match. + Matches when {mcontrol-s}ixMatch$=4$ would not match. - Matches when \FcsrMcontrolSixMatch$=5$ would not match. + Matches when {mcontrol-s}ixMatch$=5$ would not match. Other values are reserved for future use. All comparisons only look at the lower XLEN (in the current mode) - bits of the compare values and of \RcsrTdataTwo. - When \FcsrMcontrolSelect=1 and access size is N, this is further + bits of the compare values and of {csr-tdata2}. + When {mcontrol-select}=1 and access size is N, this is further reduced, and comparisons only look at the lower N bits of the - compare values and of \RcsrTdataTwo. + compare values and of {csr-tdata2}. When set, enable this trigger in M-mode. @@ -1006,10 +1006,10 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 3. + This register is accessible as {csr-tdata1} when {tdata1-type} is 3. \begin{steps}{This trigger matches when:} \item @@ -1036,34 +1036,34 @@ See also Section~\ref{stepIcount}. \end{commentary} - When \FcsrIcountCount is greater than 1 and the trigger matches, then - \FcsrIcountCount is decremented by 1. + When {icount-count} is greater than 1 and the trigger matches, then + {icount-count} is decremented by 1. - When \FcsrIcountCount is 1 and the trigger matches, then \FcsrIcountPending - becomes set. In addition \FcsrIcountCount will become 0 unless it is + When {icount-count} is 1 and the trigger matches, then {icount-pending} + becomes set. In addition {icount-count} will become 0 unless it is hard-wired to 1. The only exception to the above is when the instruction the trigger matched on is a - write to the icount trigger. In that case \FcsrIcountPending might or might - not become set if \FcsrIcountCount was 1. Afterwards \FcsrIcountCount + write to the icount trigger. In that case {icount-pending} might or might + not become set if {icount-count} was 1. Afterwards {icount-count} contains the newly written value. - When \FcsrIcountCount is 0 it stays at 0 until explicitly written. + When {icount-count} is 0 it stays at 0 until explicitly written. - When \FcsrIcountPending is set, the trigger fires just + When {icount-pending} is set, the trigger fires just before any further instructions are executed in a mode where the - trigger is enabled. As the trigger fires, \FcsrIcountPending is - cleared. In addition, if \FcsrIcountCount is hard-wired to 1 then \FcsrIcountM, - \FcsrIcountS, \FcsrIcountU, \FcsrIcountVs, and \FcsrIcountVu are all + trigger is enabled. As the trigger fires, {icount-pending} is + cleared. In addition, if {icount-count} is hard-wired to 1 then {icount-m}, + {icount-s}, {icount-u}, {icount-vs}, and {icount-vu} are all cleared. - If the trigger fires with \FcsrIcountAction=0 then zero is written to the + If the trigger fires with {icount-action}=0 then zero is written to the {\tt tval} CSR on the breakpoint trap. \begin{commentary} - The intent of \FcsrIcountPending is to cleanly handle the case where - \FcsrIcountAction is 0, \FcsrIcountM is 0, \FcsrIcountU is 1, - \FcsrIcountCount is 1, and the U-mode instruction being executed + The intent of {icount-pending} is to cleanly handle the case where + {icount-action} is 0, {icount-m} is 0, {icount-u} is 1, + {icount-count} is 1, and the U-mode instruction being executed causes a trap into M-mode. In that case we want the entire M-mode handler to be executed, and the debug trap to be taken before the next U-mode instruction. @@ -1073,10 +1073,10 @@ This trigger type is intended to be used as a single step for software monitor programs or native debug. Systems that support multiple privilege modes that want to debug software running in lower privilege - modes don't need to support \FcsrIcountCount greater than 1. + modes don't need to support {icount-count} greater than 1. \end{commentary} - If \RcsrTextraThirtytwo or \RcsrTextraSixtyfour are implemented for this + If {csr-textra32} or {csr-textra64} are implemented for this trigger, it only matches when the conditions set there are satisfied. @@ -1101,7 +1101,7 @@ and writing it has no effect. - The trigger will generally fire after \FcsrIcountCount instructions + The trigger will generally fire after {icount-count} instructions in enabled modes have been executed. See above for the precise behavior. @@ -1109,7 +1109,7 @@ When set, enable this trigger in M-mode. - This bit becomes set when \FcsrIcountCount is decremented from 1 + This bit becomes set when {icount-count} is decremented from 1 to 0. It is cleared when the trigger fires, which will happen just before executing the next instruction in one of the enabled modes. @@ -1139,19 +1139,19 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 4. + This register is accessible as {csr-tdata1} when {tdata1-type} is 4. This trigger can fire when an interrupt trap is taken. It can be enabled for individual interrupt numbers by setting the bit - corresponding to the interrupt number in \RcsrTdataTwo. The interrupt + corresponding to the interrupt number in {csr-tdata2}. The interrupt number is interpreted in the mode that the trap handler executes in. (E.g. virtualized interrupt numbers are not the same in every mode.) In addition the trigger can be enabled for non-maskable interrupts using - \FcsrItriggerNmi. + {itrigger-nmi}. \begin{commentary} If XLEN is 32, then it is not possible to set a trigger for interrupts @@ -1162,18 +1162,18 @@ \end{commentary} Hardware may only support a subset of interrupts for this trigger. A - debugger must read back \RcsrTdataTwo after writing it to confirm the + debugger must read back {csr-tdata2} after writing it to confirm the requested functionality is actually supported. When the trigger matches, it fires after the trap occurs, just before the first instruction of the trap handler is executed. If - \FcsrItriggerAction=0, the standard CSRs are updated for taking the + {itrigger-action}=0, the standard CSRs are updated for taking the breakpoint trap, and zero is written to the relevant {\tt tval} CSR. If the breakpoint trap does not go to a higher privilege mode, this will lose CSR information for the original trap. See Section~\ref{sec:nativetrigger} for more information about this case. - If \RcsrTextraThirtytwo or \RcsrTextraSixtyfour are implemented for this + If {csr-textra32} or {csr-textra64} are implemented for this trigger, it only matches when the conditions set there are satisfied. @@ -1234,16 +1234,16 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 5. + This register is accessible as {csr-tdata1} when {tdata1-type} is 5. This trigger may fire on up to XLEN of the Exception Codes defined in \Rmcause (described in the Privileged Spec, with Interrupt=0). Those - causes are configured by writing the corresponding bit in \RcsrTdataTwo. + causes are configured by writing the corresponding bit in {csr-tdata2}. (E.g.\ to trap on an illegal instruction, the debugger sets bit 2 in - \RcsrTdataTwo.) + {csr-tdata2}.) \begin{commentary} If XLEN is 32, then it is not possible to set a trigger on Exception @@ -1253,18 +1253,18 @@ \end{commentary} Hardware may support only a subset of exceptions. A debugger must read - back \RcsrTdataTwo after writing it to confirm the requested functionality + back {csr-tdata2} after writing it to confirm the requested functionality is actually supported. When the trigger matches, it fires after the trap occurs, just before the first instruction of the trap handler is executed. If - \FcsrEtriggerAction=0, the standard CSRs are updated for taking the + {etrigger-action}=0, the standard CSRs are updated for taking the breakpoint trap, and zero is written to the relevant {\tt tval} CSR. If the breakpoint trap does not go to a higher privilege mode, this will lose CSR information for the original trap. See Section~\ref{sec:nativetrigger} for more information about this case. - If \RcsrTextraThirtytwo or \RcsrTextraSixtyfour are implemented for this + If {csr-textra32} or {csr-textra64} are implemented for this trigger, it only matches when the conditions set there are satisfied. @@ -1322,10 +1322,10 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataOne when \FcsrTdataOneType is 7. + This register is accessible as {csr-tdata1} when {tdata1-type} is 7. This trigger fires when any selected TM external trigger input signals. Up to 16 TM external @@ -1335,7 +1335,7 @@ (starting with TM external trigger input 0 and continuing sequentially). Unsupported inputs are hardwired to be inactive. - If the trigger fires with \FcsrTmexttriggerAction=0 then zero is written to the + If the trigger fires with {tmexttrigger-action}=0 then zero is written to the {\tt tval} CSR on the breakpoint trap. This trigger fires asynchronously but it is subject to delegation by medeleg[3] like the other triggers. @@ -1347,7 +1347,7 @@ and fire the trigger once it is legal to do so. \begin{commentary} - \FcsrTmexttriggerIntctl is intended to be used by the {\tt clicinttrig} + {tmexttrigger-intctl} is intended to be used by the {\tt clicinttrig} mechanism from the Core-Local Interrupt Controller (CLIC) RISC-V Privileged Architecture Extensions. \end{commentary} @@ -1384,24 +1384,24 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataThree when \FcsrTdataOneType is 2, 3, 4, + This register is accessible as {csr-tdata3} when {tdata1-type} is 2, 3, 4, 5, or 6 and XLEN=32. All functionality in this register is optional. The $|value|$ bits may tie any number of upper bits to 0. The $|select|$ bits may only support 0 (ignore). - Byte-granular comparison of \RcsrScontext to \FcsrTextraThirtytwoSvalue - allows \RcsrScontext to be defined to include more than one element of comparison. - For example, software instrumentation can program the \RcsrScontext value to be + Byte-granular comparison of {csr-scontext} to {textra32-svalue} + allows {csr-scontext} to be defined to include more than one element of comparison. + For example, software instrumentation can program the {csr-scontext} value to be the concatenation of different ID contexts such as process ID and thread ID. - The user can then program byte compares based on \FcsrTextraThirtytwoSbytemask + The user can then program byte compares based on {textra32-sbytemask} to include one or more of the contexts in the compare. - Byte masking only applies to \RcsrScontext comparison; i.e when \FcsrTextraThirtytwoSselect is 1. + Byte masking only applies to {csr-scontext} comparison; i.e when {textra32-sselect} is 1. \begin{commentary} Note that sselect and mhselect filtering apply in all modes, including M-mode @@ -1411,25 +1411,25 @@ \end{commentary} - Data used together with \FcsrTextraThirtytwoMhselect. + Data used together with {textra32-mhselect}. - Ignore \FcsrTextraThirtytwoMhvalue. + Ignore {textra32-mhvalue}. This trigger will only match or fire if the low bits of - \RcsrMcontext/\RcsrHcontext equal \FcsrTextraThirtytwoMhvalue. + {csr-mcontext}/{csr-hcontext} equal {textra32-mhvalue}. 1, 5 (mcontext\_select): This trigger will only match or fire if the low bits of - \RcsrMcontext/\RcsrHcontext equal \{\FcsrTextraThirtytwoMhvalue, mhselect[2]\}. + {csr-mcontext}/{csr-hcontext} equal \{{textra32-mhvalue}, mhselect[2]\}. 2, 6 (vmid\_select): This trigger will only match or fire if VMID in hgatp equals the lower VMIDMAX - (defined in the Privileged Spec) bits of \{\FcsrTextraThirtytwoMhvalue, mhselect[2]\}. + (defined in the Privileged Spec) bits of \{{textra32-mhvalue}, mhselect[2]\}. 3, 7 (reserved): Reserved. @@ -1440,24 +1440,24 @@ When the least significant bit of this field is 1, it causes bits 7:0 - in the comparison to be ignored, when \FcsrTextraThirtytwoSselect=1. + in the comparison to be ignored, when {textra32-sselect}=1. When the next most significant bit of this field is 1, it causes bits 15:8 - to be ignored in the comparison, when \FcsrTextraThirtytwoSselect=1. + to be ignored in the comparison, when {textra32-sselect}=1. - Data used together with \FcsrTextraThirtytwoSselect. + Data used together with {textra32-sselect}. This field should be tied to 0 when S-mode is not supported. - Ignore \FcsrTextraThirtytwoSvalue. + Ignore {textra32-svalue}. This trigger will only match or fire if the low bits of - \RcsrScontext equal \FcsrTextraThirtytwoSvalue. + {csr-scontext} equal {textra32-svalue}. @@ -1465,10 +1465,10 @@ \begin{itemize}[noitemsep,nolistsep] \item the mode is VS-mode or VU-mode and ASID in \Rvsatp equals the lower ASIDMAX (defined in the Privileged Spec) bits - of \FcsrTextraThirtytwoSvalue. + of {textra32-svalue}. \item in all other modes, ASID in \Rsatp equals the lower ASIDMAX (defined in the Privileged Spec) bits of - \FcsrTextraThirtytwoSvalue. + {textra32-svalue}. \end{itemize} @@ -1478,21 +1478,21 @@ - This register provides access to the trigger selected by \RcsrTselect. + This register provides access to the trigger selected by {csr-tselect}. The reset values listed here apply to every underlying trigger. - This register is accessible as \RcsrTdataThree when \FcsrTdataOneType is 2, 3, 4, + This register is accessible as {csr-tdata3} when {tdata1-type} is 2, 3, 4, 5, or 6 and XLEN=64. The fields are defined - above, in \RcsrTextraThirtytwo. + above, in {csr-textra32}. - Byte-granular comparison of \RcsrScontext to \FcsrTextraSixtyfourSvalue in - \RcsrTextraSixtyfour allows \RcsrScontext to be defined to include + Byte-granular comparison of {csr-scontext} to {textra64-svalue} in + {csr-textra64} allows {csr-scontext} to be defined to include more than one element of comparison. For example, software instrumentation - can program the \RcsrScontext value to be the concatenation of different ID contexts + can program the {csr-scontext} value to be the concatenation of different ID contexts such as process ID and thread ID. The user can then program byte compares based on - \FcsrTextraSixtyfourSbytemask to include one or more of the contexts in the compare. + {textra64-sbytemask} to include one or more of the contexts in the compare. - Byte masking only applies to \RcsrScontext comparison; i.e when \FcsrTextraSixtyfourSselect is 1. + Byte masking only applies to {csr-scontext} comparison; i.e when {textra64-sselect} is 1. @@ -1503,7 +1503,7 @@ When the least significant bit of this field is 1, it causes bits 7:0 - in the comparison to be ignored, when \FcsrTextraSixtyfourSselect=1. + in the comparison to be ignored, when {textra64-sselect}=1. Likewise, the second bit controls the comparison of bits 15:8, third bit controls the comparison of bits 23:16, fourth bit controls the comparison of bits 31:24, and diff --git a/xml/jtag_registers.xml b/xml/jtag_registers.xml index 02d2993d..58a0ed3e 100755 --- a/xml/jtag_registers.xml +++ b/xml/jtag_registers.xml @@ -30,8 +30,8 @@ This optional field may provide additional detail about an error that occurred when communicating with a DM. It is updated whenever - \FdtmDmiOp is updated by the hardware or when 1 is written to - \FdtmDtmcsDmireset. + {dmi-op} is updated by the hardware or when 1 is written to + {dtmcs-dmireset}. This field is not implemented. @@ -67,15 +67,15 @@ Writing 1 to this bit clears the sticky error state and resets - \FdtmDtmcsErrinfo, but does not affect outstanding DMI transactions. + {dtmcs-errinfo}, but does not affect outstanding DMI transactions. This is a hint to the debugger of the minimum number of cycles a debugger should spend in Run-Test/Idle after every DMI scan to avoid a `busy' - return code (\FdtmDtmcsDmistat of 3). A debugger must still - check \FdtmDtmcsDmistat when necessary. + return code ({dtmcs-dmistat} of 3). A debugger must still + check {dtmcs-dmistat} when necessary. 0: It is not necessary to enter Run-Test/Idle at all. @@ -86,10 +86,10 @@ And so on. - Read-only alias of \FdtmDmiOp. + Read-only alias of {dmi-op}. - The size of \FdmSbaddressZeroAddress in \RdtmDmi. + The size of {sbaddress0-address} in {dtm-dmi}. @@ -110,11 +110,11 @@ sdesc="For Debugging"> This register allows access to the Debug Module Interface (DMI). - In Update-DR, the DTM starts the operation specified in \FdtmDmiOp unless the - current status reported in \FdtmDmiOp is sticky. + In Update-DR, the DTM starts the operation specified in {dmi-op} unless the + current status reported in {dmi-op} is sticky. - In Capture-DR, the DTM updates \FdmSbdataZeroData with the result from that - operation, updating \FdtmDmiOp if the current \FdtmDmiOp isn't sticky. + In Capture-DR, the DTM updates {sbdata0-data} with the result from that + operation, updating {dmi-op} if the current {dmi-op} isn't sticky. See Section~\ref{dmiaccess} for examples of how this is used. @@ -131,7 +131,7 @@ Address used for DMI access. In Update-DR this value is used to access the DM over the DMI. - \FdtmDmiOp defines what this register contains after every possible + {dmi-op} defines what this register contains after every possible operation. @@ -142,29 +142,29 @@ When the debugger writes this field, it has the following meaning: - Ignore \FdmSbdataZeroData and \FdmSbaddressZeroAddress. + Ignore {sbdata0-data} and {sbaddress0-address}. Don't send anything over the DMI during Update-DR. This operation should never result in a busy or error response. The address and data reported in the following Capture-DR are undefined. - This operation leaves the values in \FdtmDmiAddress and \FdtmDmiData + This operation leaves the values in {dmi-address} and {dmi-data} \unspecified. - Read from \FdtmDmiAddress. + Read from {dmi-address}. - When this operation succeeds, \FdtmDmiAddress contains the address - that was read from, and \FdtmDmiData contains the value that was + When this operation succeeds, {dmi-address} contains the address + that was read from, and {dmi-data} contains the value that was read. - Write \FdtmDmiData to \FdtmDmiAddress. + Write {dmi-data} to {dmi-address}. - This operation leaves the values in \FdtmDmiAddress and \FdtmDmiData + This operation leaves the values in {dmi-address} and {dmi-data} \unspecified. @@ -183,9 +183,9 @@ - A previous operation failed. The data scanned into \RdtmDmi in + A previous operation failed. The data scanned into {dtm-dmi} in this access will be ignored. This status is sticky and can be - cleared by writing \FdtmDtmcsDmireset in \RdtmDtmcs. + cleared by writing {dtmcs-dmireset} in {dtm-dtmcs}. This indicates that the DM itself or the DMI responded with an error. There are no specified cases in which the DM would @@ -193,14 +193,14 @@ returning errors. If a debugger sees this status, there might be additional - information in \FdtmDtmcsErrinfo. + information in {dtmcs-errinfo}. An operation was attempted while a DMI request is still in - progress. The data scanned into \RdtmDmi in this access will be + progress. The data scanned into {dtm-dmi} in this access will be ignored. This status is sticky and can be cleared by writing - \FdtmDtmcsDmireset in \RdtmDtmcs. If a debugger sees this status, it + {dtmcs-dmireset} in {dtm-dtmcs}. If a debugger sees this status, it needs to give the target more TCK edges between Update-DR and Capture-DR. The simplest way to do that is to add extra transitions in Run-Test/Idle. diff --git a/xml/sw_registers.xml b/xml/sw_registers.xml index e1facaa3..57968857 100644 --- a/xml/sw_registers.xml +++ b/xml/sw_registers.xml @@ -12,8 +12,8 @@ Users can write this register to change the privilege mode that the hart will run in when it resumes. - This register contains \FcsrDcsrPrv and \FcsrDcsrV from \RcsrDcsr, but in a place that the user - is expected to access. The user should not access \RcsrDcsr directly, + This register contains {dcsr-prv} and {dcsr-v} from {csr-dcsr}, but in a place that the user + is expected to access. The user should not access {csr-dcsr} directly, because doing so might interfere with the debugger. \begin{table}