From 8d5f2febf3d3780c0926ec4b4f0cd5e6c0ac7e74 Mon Sep 17 00:00:00 2001 From: Evgeniy Naydanov Date: Tue, 29 Apr 2025 18:59:15 +0300 Subject: [PATCH 1/3] Update image in `build32` Ubuntu 20.04 is no longer available. See https://github.com/actions/runner-images/issues/11101 Checkpatch-ignore: BAD_SIGN_OFF Change-Id: I0ec3e3342f9212a2a79d8dca6274e7db62ecedab Signed-off-by: Evgeniy Naydanov --- .github/workflows/linux-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/linux-build.yml b/.github/workflows/linux-build.yml index 4bcd5bb809..c21b36465c 100644 --- a/.github/workflows/linux-build.yml +++ b/.github/workflows/linux-build.yml @@ -5,7 +5,7 @@ name: Linux Build jobs: # 32-bit, clang build32: - runs-on: ubuntu-20.04 + runs-on: ubuntu-latest env: CFLAGS: -m32 CC: clang From 6a30484e3d3bcbd8dd5d7bc89f18374fc30345f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bernhard=20Rosenkr=C3=A4nzer?= Date: Tue, 6 May 2025 22:00:27 +0200 Subject: [PATCH 2/3] target/riscv: Regenerate debug_defines.{c,h} from current riscv-debug-spec MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This pulls in some improvements from the riscv-debug-spec repo, and cleans up the licensing (riscv-debug-spec changed the license to dual CC-BY-4.0 and BSD-2-Clause specifically to make sure the generated debug_defines files don't conflict with OpenOCD licensing) Signed-off-by: Bernhard Rosenkränzer --- src/target/riscv/debug_defines.c | 76 ++- src/target/riscv/debug_defines.h | 850 +++++++++++++++++-------------- 2 files changed, 527 insertions(+), 399 deletions(-) diff --git a/src/target/riscv/debug_defines.c b/src/target/riscv/debug_defines.c index d514c6e033..aca2df2885 100644 --- a/src/target/riscv/debug_defines.c +++ b/src/target/riscv/debug_defines.c @@ -1,7 +1,5 @@ -/* - * This file is auto-generated by running 'make debug_defines' in - * https://github.com/riscv/riscv-debug-spec/ (40b9a05) - */ +/* SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 */ +/* This file was auto-generated by running 'make debug_defines' in https://github.com/riscv/riscv-debug-spec/ (22a7576) */ #include "debug_defines.h" #include @@ -222,6 +220,17 @@ static const char *csr_dcsr_debugver_values[16] = { [4] = "1_0", [15] = "custom" }; +static const char *csr_dcsr_extcause_values[8] = { + [0] = "critical_error" +}; +static const char *csr_dcsr_cetrig_values[2] = { + [0] = "disabled", + [1] = "enabled" +}; +static const char *csr_dcsr_pelp_values[2] = { + [0] = "NO_LP_EXPECTED", + [1] = "LP_EXPECTED" +}; static const char *csr_dcsr_ebreakvs_values[2] = { [0] = "exception", [1] = "debug_mode" @@ -260,7 +269,8 @@ static const char *csr_dcsr_cause_values[8] = { [3] = "haltreq", [4] = "step", [5] = "resethaltreq", - [6] = "group" + [6] = "group", + [7] = "other" }; static const char *csr_dcsr_mprven_values[2] = { [0] = "disabled", @@ -350,6 +360,20 @@ static riscv_debug_reg_field_list_t csr_dcsr_get_debugver(riscv_debug_reg_ctx_t return result; } +static riscv_debug_reg_field_list_t csr_dcsr_get_extcause(riscv_debug_reg_ctx_t context) +{ + riscv_debug_reg_field_list_t result = { + .field = { + .name = "extcause", + .lsb = 0x18, + .msb = 0x1a, + .values = csr_dcsr_extcause_values + }, + .get_next = csr_dcsr_get_debugver + }; + return result; +} + static riscv_debug_reg_field_list_t csr_dcsr_get_step(riscv_debug_reg_ctx_t context) { riscv_debug_reg_field_list_t result = { @@ -359,7 +383,35 @@ static riscv_debug_reg_field_list_t csr_dcsr_get_step(riscv_debug_reg_ctx_t cont .msb = 2, .values = NULL }, - .get_next = csr_dcsr_get_debugver + .get_next = csr_dcsr_get_extcause + }; + return result; +} + +static riscv_debug_reg_field_list_t csr_dcsr_get_cetrig(riscv_debug_reg_ctx_t context) +{ + riscv_debug_reg_field_list_t result = { + .field = { + .name = "cetrig", + .lsb = 0x13, + .msb = 0x13, + .values = csr_dcsr_cetrig_values + }, + .get_next = csr_dcsr_get_step + }; + return result; +} + +static riscv_debug_reg_field_list_t csr_dcsr_get_pelp(riscv_debug_reg_ctx_t context) +{ + riscv_debug_reg_field_list_t result = { + .field = { + .name = "pelp", + .lsb = 0x12, + .msb = 0x12, + .values = csr_dcsr_pelp_values + }, + .get_next = csr_dcsr_get_cetrig }; return result; } @@ -373,7 +425,7 @@ static riscv_debug_reg_field_list_t csr_dcsr_get_ebreakvs(riscv_debug_reg_ctx_t .msb = 0x11, .values = csr_dcsr_ebreakvs_values }, - .get_next = csr_dcsr_get_step + .get_next = csr_dcsr_get_pelp }; return result; } @@ -692,12 +744,11 @@ static riscv_debug_reg_field_list_t csr_tcontrol_get_mte(riscv_debug_reg_ctx_t c static riscv_debug_reg_field_list_t csr_scontext_get_data(riscv_debug_reg_ctx_t context) { - assert(context.XLEN.is_set); riscv_debug_reg_field_list_t result = { .field = { .name = "data", .lsb = 0, - .msb = (context.XLEN.value + -1), + .msb = 0x1f, .values = NULL }, .get_next = NULL @@ -707,12 +758,11 @@ static riscv_debug_reg_field_list_t csr_scontext_get_data(riscv_debug_reg_ctx_t static riscv_debug_reg_field_list_t csr_mcontext_get_hcontext(riscv_debug_reg_ctx_t context) { - assert(context.XLEN.is_set); riscv_debug_reg_field_list_t result = { .field = { .name = "hcontext", .lsb = 0, - .msb = (context.XLEN.value + -1), + .msb = 0xd, .values = NULL }, .get_next = NULL @@ -1974,7 +2024,7 @@ static riscv_debug_reg_field_list_t csr_textra64_get_sbytemask(riscv_debug_reg_c .field = { .name = "sbytemask", .lsb = 0x24, - .msb = 0x28, + .msb = 0x27, .values = NULL }, .get_next = csr_textra64_get_mhselect @@ -1988,7 +2038,7 @@ static riscv_debug_reg_field_list_t csr_textra64_get_svalue(riscv_debug_reg_ctx_ .field = { .name = "svalue", .lsb = 2, - .msb = 0x23, + .msb = 0x21, .values = NULL }, .get_next = csr_textra64_get_sbytemask diff --git a/src/target/riscv/debug_defines.h b/src/target/riscv/debug_defines.h index dbe5142a8e..0f6691b019 100644 --- a/src/target/riscv/debug_defines.h +++ b/src/target/riscv/debug_defines.h @@ -1,7 +1,5 @@ -/* - * This file is auto-generated by running 'make debug_defines' in - * https://github.com/riscv/riscv-debug-spec/ (40b9a05) - */ +/* SPDX-License-Identifier: BSD-2-Clause OR CC-BY-4.0 */ +/* This file was auto-generated by running 'make debug_defines' in https://github.com/riscv/riscv-debug-spec/ (22a7576) */ #ifndef DEBUG_DEFINES_H #define DEBUG_DEFINES_H @@ -35,8 +33,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}. */ #define DTM_DTMCS_ERRINFO_OFFSET 0x12ULL #define DTM_DTMCS_ERRINFO_LENGTH 3ULL @@ -79,7 +77,7 @@ #define DTM_DTMCS_DTMHARDRESET 0x20000ULL /* * 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. */ #define DTM_DTMCS_DMIRESET_OFFSET 0x10ULL #define DTM_DTMCS_DMIRESET_LENGTH 1ULL @@ -88,8 +86,8 @@ * 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. * @@ -103,13 +101,13 @@ #define DTM_DTMCS_IDLE_LENGTH 3ULL #define DTM_DTMCS_IDLE 0x7000ULL /* - * Read-only alias of \FdtmDmiOp. + * Read-only alias of {dmi-op}. */ #define DTM_DTMCS_DMISTAT_OFFSET 0xaULL #define DTM_DTMCS_DMISTAT_LENGTH 2ULL #define DTM_DTMCS_DMISTAT 0xc00ULL /* - * The size of \FdmSbaddressZeroAddress in \RdtmDmi. + * The size of {dmi-address} in {dtm-dmi}. */ #define DTM_DTMCS_ABITS_OFFSET 4ULL #define DTM_DTMCS_ABITS_LENGTH 6ULL @@ -133,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. */ #define DTM_DMI_ADDRESS_OFFSET 0x22ULL @@ -153,30 +151,30 @@ #define DTM_DMI_OP_LENGTH 2ULL #define DTM_DMI_OP 3ULL /* - * nop: Ignore \FdmSbdataZeroData and \FdmSbaddressZeroAddress. + * nop: 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. + * This operation should never affect DMI busy or error status. * The address and data reported in the following Capture-DR * are undefined. * - * This operation leaves the values in \FdtmDmiAddress and \FdtmDmiData - * \unspecified. + * This operation leaves the values in {dmi-address} and {dmi-data} + * UNSPECIFIED. */ #define DTM_DMI_OP_NOP 0 /* - * read: Read from \FdtmDmiAddress. + * read: 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. */ #define DTM_DMI_OP_READ 1 /* - * write: Write \FdtmDmiData to \FdtmDmiAddress. + * write: Write {dmi-data} to {dmi-address}. * - * This operation leaves the values in \FdtmDmiAddress and \FdtmDmiData - * \unspecified. + * This operation leaves the values in {dmi-address} and {dmi-data} + * UNSPECIFIED. */ #define DTM_DMI_OP_WRITE 2 /* @@ -193,9 +191,9 @@ * reserved: Reserved. */ /* - * failed: A previous operation failed. The data scanned into \RdtmDmi in + * failed: 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 @@ -203,14 +201,14 @@ * returning errors. * * If a debugger sees this status, there might be additional - * information in \FdtmDtmcsErrinfo. + * information in {dtmcs-errinfo}. */ #define DTM_DMI_OP_FAILED 2 /* - * busy: An operation was attempted while a DMI request is still in - * progress. The data scanned into \RdtmDmi in this access will be + * busy: A DMI operation was attempted while a prior DMI operation was still in + * 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. @@ -233,16 +231,82 @@ * available version of this spec. */ #define CSR_DCSR_DEBUGVER_CUSTOM 15 +/* + * When {dcsr-cause} is 7, this optional field contains the value of a + * more specific halt reason than "other." Otherwise it contains 0. + */ +#define CSR_DCSR_EXTCAUSE_OFFSET 0x18ULL +#define CSR_DCSR_EXTCAUSE_LENGTH 3ULL +#define CSR_DCSR_EXTCAUSE 0x7000000ULL +/* + * critical error: The hart entered a critical error state, as defined in the + * ((Smdbltrp)) extension. + */ +#define CSR_DCSR_EXTCAUSE_CRITICAL_ERROR 0 +/* + * All other values are reserved for future versions of this spec, or + * for use by other RISC-V extensions. + */ +/* + * This bit is part of ((Smdbltrp)) and only exists when that extension + * is implemented. + */ +#define CSR_DCSR_CETRIG_OFFSET 0x13ULL +#define CSR_DCSR_CETRIG_LENGTH 1ULL +#define CSR_DCSR_CETRIG 0x80000ULL +/* + * disabled: A hart in a critical error state does not enter Debug Mode but + * instead asserts the critical-error signal to the platform. + */ +#define CSR_DCSR_CETRIG_DISABLED 0 +/* + * enabled: A hart in a critical error state enters Debug Mode instead of + * asserting the critical-error signal to the platform. Upon such + * entry into Debug Mode, the cause field is set to 7, and the + * extcause field is set to 0, indicating a critical error + * triggered the Debug Mode entry. This cause has the highest + * priority among all reasons for entering Debug Mode. Resuming + * from Debug Mode following an entry from the critical error state + * returns the hart to the critical error state. + */ +#define CSR_DCSR_CETRIG_ENABLED 1 +/* + * [NOTE] + * ==== + * When {dcsr-cetrig} is 1, resuming from Debug Mode + * following an entry due to a critical error will result in an + * immediate re-entry into Debug Mode due to the critical error. + * The debugger may resume with {dcsr-cetrig} set to 0 to allow the + * platform defined actions on critical-error signal to occur. + * Other possible actions include initiating a hart or platform + * reset using the Debug Module reset control. + * ==== + */ +/* + * This bit is part of ((Zicfilp)) and only exists when that extension + * is implemented. + */ +#define CSR_DCSR_PELP_OFFSET 0x12ULL +#define CSR_DCSR_PELP_LENGTH 1ULL +#define CSR_DCSR_PELP 0x40000ULL +/* + * NO_LP_EXPECTED: No landing pad instruction expected. + */ +#define CSR_DCSR_PELP_NO_LP_EXPECTED 0 +/* + * LP_EXPECTED: A landing pad instruction is expected. + */ +#define CSR_DCSR_PELP_LP_EXPECTED 1 #define CSR_DCSR_EBREAKVS_OFFSET 0x11ULL #define CSR_DCSR_EBREAKVS_LENGTH 1ULL #define CSR_DCSR_EBREAKVS 0x20000ULL /* - * exception: {\tt ebreak} instructions in VS-mode behave as described in the + * exception: `ebreak` instructions in VS-mode behave as described in the * Privileged Spec. */ #define CSR_DCSR_EBREAKVS_EXCEPTION 0 /* - * debug mode: {\tt ebreak} instructions in VS-mode enter Debug Mode. + * debug mode: `ebreak` instructions in VS-mode enter Debug Mode. */ #define CSR_DCSR_EBREAKVS_DEBUG_MODE 1 /* @@ -252,12 +316,12 @@ #define CSR_DCSR_EBREAKVU_LENGTH 1ULL #define CSR_DCSR_EBREAKVU 0x10000ULL /* - * exception: {\tt ebreak} instructions in VU-mode behave as described in the + * exception: `ebreak` instructions in VU-mode behave as described in the * Privileged Spec. */ #define CSR_DCSR_EBREAKVU_EXCEPTION 0 /* - * debug mode: {\tt ebreak} instructions in VU-mode enter Debug Mode. + * debug mode: `ebreak` instructions in VU-mode enter Debug Mode. */ #define CSR_DCSR_EBREAKVU_DEBUG_MODE 1 /* @@ -267,24 +331,24 @@ #define CSR_DCSR_EBREAKM_LENGTH 1ULL #define CSR_DCSR_EBREAKM 0x8000ULL /* - * exception: {\tt ebreak} instructions in M-mode behave as described in the + * exception: `ebreak` instructions in M-mode behave as described in the * Privileged Spec. */ #define CSR_DCSR_EBREAKM_EXCEPTION 0 /* - * debug mode: {\tt ebreak} instructions in M-mode enter Debug Mode. + * debug mode: `ebreak` instructions in M-mode enter Debug Mode. */ #define CSR_DCSR_EBREAKM_DEBUG_MODE 1 #define CSR_DCSR_EBREAKS_OFFSET 0xdULL #define CSR_DCSR_EBREAKS_LENGTH 1ULL #define CSR_DCSR_EBREAKS 0x2000ULL /* - * exception: {\tt ebreak} instructions in S-mode behave as described in the + * exception: `ebreak` instructions in S-mode behave as described in the * Privileged Spec. */ #define CSR_DCSR_EBREAKS_EXCEPTION 0 /* - * debug mode: {\tt ebreak} instructions in S-mode enter Debug Mode. + * debug mode: `ebreak` instructions in S-mode enter Debug Mode. */ #define CSR_DCSR_EBREAKS_DEBUG_MODE 1 /* @@ -294,12 +358,12 @@ #define CSR_DCSR_EBREAKU_LENGTH 1ULL #define CSR_DCSR_EBREAKU 0x1000ULL /* - * exception: {\tt ebreak} instructions in U-mode behave as described in the + * exception: `ebreak` instructions in U-mode behave as described in the * Privileged Spec. */ #define CSR_DCSR_EBREAKU_EXCEPTION 0 /* - * debug mode: {\tt ebreak} instructions in U-mode enter Debug Mode. + * debug mode: `ebreak` instructions in U-mode enter Debug Mode. */ #define CSR_DCSR_EBREAKU_DEBUG_MODE 1 /* @@ -310,13 +374,13 @@ #define CSR_DCSR_STEPIE 0x800ULL /* * interrupts disabled: Interrupts (including NMI) are disabled during single stepping - * with \FcsrDcsrStep set. + * with {dcsr-step} set. * This value should be supported. */ #define CSR_DCSR_STEPIE_INTERRUPTS_DISABLED 0 /* * interrupts enabled: Interrupts (including NMI) are enabled during single stepping - * with \FcsrDcsrStep set. + * with {dcsr-step} set. */ #define CSR_DCSR_STEPIE_INTERRUPTS_ENABLED 1 /* @@ -335,9 +399,9 @@ #define CSR_DCSR_STOPCOUNT_NORMAL 0 /* * freeze: Don't increment any hart-local counters while in Debug Mode or - * on {\tt ebreak} instructions that cause entry into Debug Mode. - * These counters include the {\tt instret} CSR. On single-hart cores - * {\tt cycle} should be stopped, but on multi-hart cores it must keep + * on `ebreak` instructions that cause entry into Debug Mode. + * These counters include the `instret` CSR. On single-hart cores + * `cycle` should be stopped, but on multi-hart cores it must keep * incrementing. */ #define CSR_DCSR_STOPCOUNT_FREEZE 1 @@ -348,16 +412,16 @@ #define CSR_DCSR_STOPTIME_LENGTH 1ULL #define CSR_DCSR_STOPTIME 0x200ULL /* - * normal: \Rtime continues to reflect \Rmtime. + * normal: `time` continues to reflect `mtime`. */ #define CSR_DCSR_STOPTIME_NORMAL 0 /* - * freeze: \Rtime is frozen at the time that Debug Mode was entered. When - * leaving Debug Mode, \Rtime will reflect the latest - * value of \Rmtime again. + * freeze: `time` is frozen at the time that Debug Mode was entered. When + * leaving Debug Mode, `time` will reflect the latest + * value of `mtime` again. * - * While all harts have \FcsrDcsrStoptime=1 and are in Debug Mode, - * \Rmtime is allowed to stop incrementing. + * While all harts have {dcsr-stoptime}=1 and are in Debug Mode, + * `mtime` is allowed to stop incrementing. */ #define CSR_DCSR_STOPTIME_FREEZE 1 /* @@ -367,14 +431,14 @@ * 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 - * priority. See table~\ref{tab:dcsrcausepriority} for priorities. + * cycle, hardware should set {dcsr-cause} to the cause with the highest + * priority. See <> for priorities. */ #define CSR_DCSR_CAUSE_OFFSET 6ULL #define CSR_DCSR_CAUSE_LENGTH 3ULL #define CSR_DCSR_CAUSE 0x1c0ULL /* - * ebreak: An {\tt ebreak} instruction was executed. + * ebreak: An `ebreak` instruction was executed. */ #define CSR_DCSR_CAUSE_EBREAK 1 /* @@ -382,15 +446,15 @@ */ #define CSR_DCSR_CAUSE_TRIGGER 2 /* - * haltreq: The debugger requested entry to Debug Mode using \FdmDmcontrolHaltreq. + * haltreq: The debugger requested entry to Debug Mode using {dmcontrol-haltreq}. */ #define CSR_DCSR_CAUSE_HALTREQ 3 /* - * step: The hart single stepped because \FcsrDcsrStep was set. + * step: The hart single stepped because {dcsr-step} was set. */ #define CSR_DCSR_CAUSE_STEP 4 /* - * resethaltreq: The hart halted directly out of reset due to \Fresethaltreq. It + * resethaltreq: The hart halted directly out of reset due to {resethaltreq} It * is also acceptable to report 3 when this happens. */ #define CSR_DCSR_CAUSE_RESETHALTREQ 5 @@ -400,12 +464,13 @@ */ #define CSR_DCSR_CAUSE_GROUP 6 /* - * Other values are reserved for future use. + * other: The hart halted for a reason other than the ones mentioned above. + * {dcsr-extcause} may contain a more specific reason. */ +#define CSR_DCSR_CAUSE_OTHER 7 /* * Extends the prv field with the virtualization mode the hart was operating - * in when Debug Mode was entered. The encoding is described in Table - * \ref{tab:privmode}. + * in when Debug Mode was entered. The encoding is described in <>. * A debugger can change this value to change the hart's virtualization mode * when exiting Debug Mode. * This bit is hardwired to 0 on harts that do not support virtualization mode. @@ -417,11 +482,11 @@ #define CSR_DCSR_MPRVEN_LENGTH 1ULL #define CSR_DCSR_MPRVEN 0x10ULL /* - * disabled: \FcsrMstatusMprv in \Rmstatus is ignored in Debug Mode. + * disabled: `mprv` in `mstatus` is ignored in Debug Mode. */ #define CSR_DCSR_MPRVEN_DISABLED 0 /* - * enabled: \FcsrMstatusMprv in \Rmstatus takes effect in Debug Mode. + * enabled: `mprv` in `mstatus` takes effect in Debug Mode. */ #define CSR_DCSR_MPRVEN_ENABLED 1 /* @@ -439,7 +504,7 @@ #define CSR_DCSR_NMIP 8ULL /* * When set and not in Debug Mode, the hart will only execute a single - * instruction and then enter Debug Mode. See Section~\ref{stepBit} + * instruction and then enter Debug Mode. See xref:stepbit[] * for details. * * The debugger must not change the value of this bit while the hart @@ -450,8 +515,7 @@ #define CSR_DCSR_STEP 4ULL /* * Contains the privilege mode the hart was operating in when Debug - * Mode was entered. The encoding is described in Table - * \ref{tab:privmode}. A debugger can change this value to change + * Mode was entered. The encoding is described in <>. A debugger can change this value to change * the hart's privilege mode when exiting Debug Mode. * * Not all privilege modes are supported on all harts. If the @@ -482,7 +546,7 @@ #define CSR_TDATA1_TYPE_LENGTH 4ULL #define CSR_TDATA1_TYPE(XLEN) (0xfULL * (1ULL << ((XLEN) + -4ULL))) /* - * none: There is no trigger at this \RcsrTselect. + * none: There is no trigger at this {csr-tselect}. */ #define CSR_TDATA1_TYPE_NONE 0 /* @@ -492,34 +556,34 @@ #define CSR_TDATA1_TYPE_LEGACY 1 /* * mcontrol: 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}. */ #define CSR_TDATA1_TYPE_MCONTROL 2 /* * icount: 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}. */ #define CSR_TDATA1_TYPE_ICOUNT 3 /* * itrigger: 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}. */ #define CSR_TDATA1_TYPE_ITRIGGER 4 /* * etrigger: 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}. */ #define CSR_TDATA1_TYPE_ETRIGGER 5 /* * mcontrol6: 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-mcontrol6}. This is similar * to a type 2 trigger, but provides additional functionality and * should be used instead of type 2 in newer implementations. */ #define CSR_TDATA1_TYPE_MCONTROL6 6 /* * tmexttrigger: 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}. */ #define CSR_TDATA1_TYPE_TMEXTTRIGGER 7 /* @@ -528,10 +592,10 @@ #define CSR_TDATA1_TYPE_CUSTOM_LOW 12 #define CSR_TDATA1_TYPE_CUSTOM_HIGH 14 /* - * disabled: This trigger is disabled. In this state, \RcsrTdataTwo and - * \RcsrTdataThree can be written with any value that is supported for + * disabled: 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. */ #define CSR_TDATA1_TYPE_DISABLED 15 @@ -539,19 +603,19 @@ * Other values are reserved for future use. */ /* - * 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. */ #define CSR_TDATA1_DMODE_OFFSET(XLEN) ((XLEN) + -5ULL) #define CSR_TDATA1_DMODE_LENGTH 1ULL #define CSR_TDATA1_DMODE(XLEN) (1ULL << ((XLEN) + -5ULL)) /* - * both: Both Debug and M-mode can write the {\tt tdata} registers at the - * selected \RcsrTselect. + * both: Both Debug and M-mode can write the `tdata` registers at the + * selected {csr-tselect}. */ #define CSR_TDATA1_DMODE_BOTH 0 /* - * dmode: Only Debug Mode can write the {\tt tdata} registers at the - * selected \RcsrTselect. Writes from other modes are ignored. + * dmode: Only Debug Mode can write the `tdata` registers at the + * selected {csr-tselect}. Writes from other modes are ignored. */ #define CSR_TDATA1_DMODE_DMODE 1 /* @@ -559,11 +623,11 @@ * 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. */ @@ -589,14 +653,12 @@ * 0: Supports triggers as described in this spec at commit 5a5c078, * 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 - * than 64 bits are different. - * \end{steps} + * In these older versions: + * + * . {csr-mcontrol6} has a timing bit identical to {mcontrol-timing} + * . {mcontrol6-hit0} behaves just as {mcontrol-hit}. + * . {mcontrol6-hit1} is read-only 0. + * . Encodings for {mcontrol6-size} for access sizes larger than 64 bits are different. */ #define CSR_TINFO_VERSION_0 0 /* @@ -605,7 +667,7 @@ */ #define CSR_TINFO_VERSION_1 1 /* - * 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. * @@ -619,12 +681,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. + * xref: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}. */ #define CSR_TCONTROL_MPTE_OFFSET 7ULL #define CSR_TCONTROL_MPTE_LENGTH 1ULL @@ -644,8 +706,7 @@ */ #define CSR_TCONTROL_MTE_ENABLED 1 /* - * 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 `mret` is executed, {tcontrol-mte} is set to the value of {tcontrol-mpte}. */ #define CSR_HCONTEXT 0x6a8 #define CSR_SCONTEXT 0x5a8 @@ -655,28 +716,28 @@ * specific context. * * An implementation may tie any number of high bits in this field to - * 0. It's recommended to implement no more than 16 bits on RV32, and - * 34 on RV64. + * 0. It's recommended to implement 16 bits on RV32 and 32 bits on + * RV64. */ #define CSR_SCONTEXT_DATA_OFFSET 0ULL -#define CSR_SCONTEXT_DATA_LENGTH(XLEN) (XLEN) -#define CSR_SCONTEXT_DATA(XLEN) ((1ULL << (XLEN)) + -1ULL) +#define CSR_SCONTEXT_DATA_LENGTH 0x20ULL +#define CSR_SCONTEXT_DATA 0xffffffffULL #define CSR_MCONTEXT 0x7a8 /* - * 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, - * it's recommended to implement no more than 7 bits on RV32 - * and 14 on RV64. + * 6 bits on RV32 and 13 bits on RV64 (as visible through the + * {csr-mcontext} register). If the H extension is implemented, + * it's recommended to implement 7 bits on RV32 + * and 14 bits on RV64. */ #define CSR_MCONTEXT_HCONTEXT_OFFSET 0ULL -#define CSR_MCONTEXT_HCONTEXT_LENGTH(XLEN) (XLEN) -#define CSR_MCONTEXT_HCONTEXT(XLEN) ((1ULL << (XLEN)) + -1ULL) +#define CSR_MCONTEXT_HCONTEXT_LENGTH 0xeULL +#define CSR_MCONTEXT_HCONTEXT 0x3fffULL #define CSR_MSCONTEXT 0x7aa #define CSR_MCONTROL 0x7a1 #define CSR_MCONTROL_TYPE_OFFSET(XLEN) ((XLEN) + -4ULL) @@ -687,11 +748,11 @@ #define CSR_MCONTROL_DMODE(XLEN) (1ULL << ((XLEN) + -5ULL)) /* * 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. + * 2^63^ bytes in size. */ #define CSR_MCONTROL_MASKMAX_OFFSET(XLEN) ((XLEN) + -0xbULL) #define CSR_MCONTROL_MASKMAX_LENGTH 6ULL @@ -699,7 +760,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. */ #define CSR_MCONTROL_SIZEHI_OFFSET 0x15ULL @@ -743,19 +804,19 @@ /* * before: 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. `xepc` 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, * memory-mapped I/O addresses. * * If an instruction matches this trigger and the instruction performs - * multiple memory accesses, it is \unspecified which memory accesses + * multiple memory accesses, it is UNSPECIFIED which memory accesses * have completed before the trigger fires. */ #define CSR_MCONTROL_TIMING_BEFORE 0 @@ -763,39 +824,39 @@ * after: The action for this trigger will be taken after the instruction * 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 + * than to not implement them at all. `xepc` or + * {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. */ #define CSR_MCONTROL_TIMING_AFTER 1 /* * 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-store}. 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: */ #define CSR_MCONTROL_SIZELO_OFFSET 0x10ULL #define CSR_MCONTROL_SIZELO_LENGTH 2ULL #define CSR_MCONTROL_SIZELO 0x30000ULL /* * any: The trigger will attempt to match against an access of any size. - * The behavior is only well-defined if $|select|=0$, or if the access + * The behavior is only well-defined if {mcontrol-select}=0, or if the access * size is XLEN. */ #define CSR_MCONTROL_SIZELO_ANY 0 @@ -842,24 +903,24 @@ /* * 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. */ /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_MCONTROL_ACTION_OFFSET 0xcULL #define CSR_MCONTROL_ACTION_LENGTH 4ULL @@ -905,10 +966,10 @@ */ #define CSR_MCONTROL_CHAIN_ENABLED 1 /* - * A trigger chain starts on the first trigger with $|chain|=1$ after - * a trigger with $|chain|=0$, or simply on the first trigger if that - * has $|chain|=1$. It ends on the first trigger after that which has - * $|chain|=0$. This final trigger is part of the chain. The action + * A trigger chain starts on the first trigger with `chain`=1 after + * a trigger with `chain`=0, or simply on the first trigger if that + * has `chain`=1. It ends on the first trigger after that which has + * `chain`=0. This final trigger is part of the chain. The action * on all but the final trigger is ignored. The action on that final * trigger will be taken if and only if all the triggers in the chain * match at the same time. @@ -916,83 +977,83 @@ * 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. */ #define CSR_MCONTROL_MATCH_OFFSET 7ULL #define CSR_MCONTROL_MATCH_LENGTH 4ULL #define CSR_MCONTROL_MATCH 0x780ULL /* - * equal: Matches when any compare value equals \RcsrTdataTwo. + * equal: Matches when any compare value equals {csr-tdata2}. */ #define CSR_MCONTROL_MATCH_EQUAL 0 /* - * napot: Matches when the top $M$ bits of any compare value match the top - * $M$ bits of \RcsrTdataTwo. - * $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|$ - * and $M\gt0$ , otherwise it's undefined on what conditions the + * napot: Matches when the top `M` bits of any compare value match the top + * `M` bits of {csr-tdata2}. + * `M` is `XLEN-1` minus the index of the least-significant + * bit containing 0 in {csr-tdata2}. Debuggers should only write values + * to {csr-tdata2} such that `M` + {mcontrol-maskmax} ≥ `XLEN` + * and `M` > 0, otherwise it's undefined on what conditions the * trigger will match. */ #define CSR_MCONTROL_MATCH_NAPOT 1 /* * ge: Matches when any compare value is greater than (unsigned) or - * equal to \RcsrTdataTwo. + * equal to {csr-tdata2}. */ #define CSR_MCONTROL_MATCH_GE 2 /* * lt: Matches when any compare value is less than (unsigned) - * \RcsrTdataTwo. + * {csr-tdata2}. */ #define CSR_MCONTROL_MATCH_LT 3 /* - * mask low: Matches when $\frac{|XLEN|}{2}-1$:$0$ of any compare value - * equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after - * $\frac{|XLEN|}{2}-1$:$0$ of the compare value is ANDed with - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + * mask low: Matches when latexmath:[$\frac{XLEN}{2}-{1:0}] of any compare value + * equals latexmath:[$\frac{XLEN}{2}-{1:0}] of {csr-tdata2} after + * latexmath:[$\frac{XLEN}{2}-{1:0}] of the compare value is ANDed with + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of {csr-tdata2}. */ #define CSR_MCONTROL_MATCH_MASK_LOW 4 /* - * mask high: Matches when $|XLEN|-1$:$\frac{|XLEN|}{2}$ of any compare - * value equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of the compare value is ANDed with - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + * mask high: Matches when `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of any compare + * value equals latexmath:[$\frac{XLEN}{2}-{1:0}] of {csr-tdata2} after + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of the compare value is ANDed with + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of {csr-tdata2}. */ #define CSR_MCONTROL_MATCH_MASK_HIGH 5 /* - * not equal: Matches when \FcsrMcontrolMatch$=0$ would not match. + * not equal: Matches when {mcontrol-match}=0 would not match. */ #define CSR_MCONTROL_MATCH_NOT_EQUAL 8 /* - * not napot: Matches when \FcsrMcontrolMatch$=1$ would not match. + * not napot: Matches when {mcontrol-match}=1 would not match. */ #define CSR_MCONTROL_MATCH_NOT_NAPOT 9 /* - * not mask low: Matches when \FcsrMcontrolMatch$=4$ would not match. + * not mask low: Matches when {mcontrol-match}=4 would not match. */ #define CSR_MCONTROL_MATCH_NOT_MASK_LOW 12 /* - * not mask high: Matches when \FcsrMcontrolMatch$=5$ would not match. + * not mask high: Matches when {mcontrol-match}=5 would not match. */ #define CSR_MCONTROL_MATCH_NOT_MASK_HIGH 13 /* * 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. @@ -1082,8 +1143,8 @@ #define CSR_MCONTROL6_VU_LENGTH 1ULL #define CSR_MCONTROL6_VU 0x800000ULL /* - * If they are implemented, \FcsrMcontrolSixHitOne (MSB) and - * \FcsrMcontrolSixHitZero (LSB) combine into a single 2-bit field. + * If they are implemented, {mcontrol6-hit1} (MSB) and + * {mcontrol6-hit0} (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. @@ -1102,16 +1163,16 @@ * before: The trigger fired before the instruction that matched it was * retired, but after all preceding instructions are retired. This * explicitly allows for instructions to be partially executed, as - * described in Section \ref{sec:multistate}. + * described in xref:multistate[]. * - * \Rxepc or \RcsrDpc (depending on \FcsrMcontrolSixAction) must be set + * `xepc` or {csr-dpc} (depending on {mcontrol6-action}) must be set * to the virtual address of the instruction that matched. */ #define CSR_MCONTROL6_HIT0_BEFORE 1 /* * after: 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 + * `xepc` or {csr-dpc} (depending on {mcontrol6-action}) must be set * to the virtual address of the next instruction that must be executed * to preserve the program flow. */ @@ -1119,7 +1180,7 @@ /* * immediately after: 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 + * `xepc` or {csr-dpc} (depending on {mcontrol6-action}) must be set * to the virtual address of the next instruction that must be executed * to preserve the program flow. * @@ -1153,8 +1214,8 @@ #define CSR_MCONTROL6_SIZE 0x70000ULL /* * any: The trigger will attempt to match against an access of any size. - * The behavior is only well-defined if $|select|=0$, or if the access - * size is XLEN. + * The behavior is only well-defined if {mcontrol6-select}=0, or if the + * access size is XLEN. */ #define CSR_MCONTROL6_SIZE_ANY 0 /* @@ -1188,24 +1249,24 @@ /* * 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 + * ({mcontrol6-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 (\FcsrMcontrolSixSelect=1) can only be supported + * {csr-tdata2} is of size XLEN, there is a known limitation that + * data value triggers ({mcontrol6-select}=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 ({mcontrol6-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. */ /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_MCONTROL6_ACTION_OFFSET 0xcULL #define CSR_MCONTROL6_ACTION_LENGTH 4ULL @@ -1251,10 +1312,10 @@ */ #define CSR_MCONTROL6_CHAIN_ENABLED 1 /* - * A trigger chain starts on the first trigger with $|chain|=1$ after - * a trigger with $|chain|=0$, or simply on the first trigger if that - * has $|chain|=1$. It ends on the first trigger after that which has - * $|chain|=0$. This final trigger is part of the chain. The action + * A trigger chain starts on the first trigger with `chain`=1 after + * a trigger with `chain`=0, or simply on the first trigger if that + * has `chain`=1. It ends on the first trigger after that which has + * `chain`=0. This final trigger is part of the chain. The action * on all but the final trigger is ignored. The action on that final * trigger will be taken if and only if all the triggers in the chain * match at the same time. @@ -1262,85 +1323,85 @@ * 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 {mcontrol6-chain} affects the next trigger, hardware must zero it in + * writes to {csr-mcontrol6} that set {tdata1-dmode} to 0 if the next trigger has + * {tdata1-dmode} of 1. + * In addition hardware should ignore writes to {csr-mcontrol6} that set + * {tdata1-dmode} to 1 if the previous trigger has both {tdata1-dmode} of 0 and + * {mcontrol6-chain} of 1. Debuggers must avoid the latter case by checking + * {mcontrol6-chain} on the previous trigger if they're writing {csr-mcontrol6}. * * 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. + * {mcontrol6-chain} in writes to {csr-mcontrol6} that would make the chain too long. */ #define CSR_MCONTROL6_MATCH_OFFSET 7ULL #define CSR_MCONTROL6_MATCH_LENGTH 4ULL #define CSR_MCONTROL6_MATCH 0x780ULL /* - * equal: Matches when any compare value equals \RcsrTdataTwo. + * equal: Matches when any compare value equals {csr-tdata2}. */ #define CSR_MCONTROL6_MATCH_EQUAL 0 /* - * napot: Matches when the top $M$ bits of any compare value match the top - * $M$ bits of \RcsrTdataTwo. - * $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 - * 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$. + * napot: Matches when the top `M` bits of any compare value match the top + * `M` bits of {csr-tdata2}. + * `M` is `XLEN-1` minus the index of the least-significant bit + * 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 {csr-tdata2} require M + `maskmax6` ≥ `XLEN` and `M` > 0. * See above for how to determine maskmax6. */ #define CSR_MCONTROL6_MATCH_NAPOT 1 /* * ge: Matches when any compare value is greater than (unsigned) or - * equal to \RcsrTdataTwo. + * equal to {csr-tdata2}. */ #define CSR_MCONTROL6_MATCH_GE 2 /* * lt: Matches when any compare value is less than (unsigned) - * \RcsrTdataTwo. + * {csr-tdata2}. */ #define CSR_MCONTROL6_MATCH_LT 3 /* - * mask low: Matches when $\frac{|XLEN|}{2}-1$:$0$ of any compare value - * equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after - * $\frac{|XLEN|}{2}-1$:$0$ of the compare value is ANDed with - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + * mask low: Matches when latexmath:[$\frac{XLEN}{2}-{1:0}] of any compare value + * equals latexmath:[$\frac{XLEN}{2}-{1:0}] of {csr-tdata2} after + * latexmath:[$\frac{XLEN}{2}-{1:0}] of the compare value is ANDed with + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of {csr-tdata2}. */ #define CSR_MCONTROL6_MATCH_MASK_LOW 4 /* - * mask high: Matches when $|XLEN|-1$:$\frac{|XLEN|}{2}$ of any compare - * value equals $\frac{|XLEN|}{2}-1$:$0$ of \RcsrTdataTwo after - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of the compare value is ANDed with - * $|XLEN|-1$:$\frac{|XLEN|}{2}$ of \RcsrTdataTwo. + * mask high: Matches when `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of any compare + * value equals latexmath:[$\frac{XLEN}{2}-{1:0}] of {csr-tdata2} after + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of the compare value is ANDed with + * `XLEN-1`:latexmath:[$\frac{XLEN}{2}$] of {csr-tdata2}. */ #define CSR_MCONTROL6_MATCH_MASK_HIGH 5 /* - * not equal: Matches when \FcsrMcontrolSixMatch$=0$ would not match. + * not equal: Matches when {mcontrol6-match} `=0` would not match. */ #define CSR_MCONTROL6_MATCH_NOT_EQUAL 8 /* - * not napot: Matches when \FcsrMcontrolSixMatch$=1$ would not match. + * not napot: Matches when {mcontrol6-match} `=1` would not match. */ #define CSR_MCONTROL6_MATCH_NOT_NAPOT 9 /* - * not mask low: Matches when \FcsrMcontrolSixMatch$=4$ would not match. + * not mask low: Matches when {mcontrol6-match} `=4` would not match. */ #define CSR_MCONTROL6_MATCH_NOT_MASK_LOW 12 /* - * not mask high: Matches when \FcsrMcontrolSixMatch$=5$ would not match. + * not mask high: Matches when {mcontrol6-match} `=5` would not match. */ #define CSR_MCONTROL6_MATCH_NOT_MASK_HIGH 13 /* * 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. @@ -1433,7 +1494,7 @@ #define CSR_ICOUNT_HIT_LENGTH 1ULL #define CSR_ICOUNT_HIT 0x1000000ULL /* - * 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. */ #define CSR_ICOUNT_COUNT_OFFSET 0xaULL @@ -1446,7 +1507,7 @@ #define CSR_ICOUNT_M_LENGTH 1ULL #define CSR_ICOUNT_M 0x200ULL /* - * 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. */ @@ -1471,7 +1532,7 @@ #define CSR_ICOUNT_U 0x40ULL /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_ICOUNT_ACTION_OFFSET 0ULL #define CSR_ICOUNT_ACTION_LENGTH 6ULL @@ -1573,7 +1634,7 @@ #define CSR_ITRIGGER_U 0x40ULL /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_ITRIGGER_ACTION_OFFSET 0ULL #define CSR_ITRIGGER_ACTION_LENGTH 6ULL @@ -1668,7 +1729,7 @@ #define CSR_ETRIGGER_U 0x40ULL /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_ETRIGGER_ACTION_OFFSET 0ULL #define CSR_ETRIGGER_ACTION_LENGTH 6ULL @@ -1734,7 +1795,7 @@ #define CSR_TMEXTTRIGGER_SELECT 0x3fffc0ULL /* * The action to take when the trigger fires. The values are explained - * in Table~\ref{tab:action}. + * in xref:tab:action[]. */ #define CSR_TMEXTTRIGGER_ACTION_OFFSET 0ULL #define CSR_TMEXTTRIGGER_ACTION_LENGTH 6ULL @@ -1769,7 +1830,7 @@ #define CSR_TMEXTTRIGGER_ACTION_EXTERNAL1 9 #define CSR_TEXTRA32 0x7a3 /* - * Data used together with \FcsrTextraThirtytwoMhselect. + * Data used together with {textra32-mhselect}. */ #define CSR_TEXTRA32_MHVALUE_OFFSET 0x1aULL #define CSR_TEXTRA32_MHVALUE_LENGTH 6ULL @@ -1778,22 +1839,22 @@ #define CSR_TEXTRA32_MHSELECT_LENGTH 3ULL #define CSR_TEXTRA32_MHSELECT 0x3800000ULL /* - * ignore: Ignore \FcsrTextraThirtytwoMhvalue. + * ignore: Ignore {textra32-mhvalue}. */ #define CSR_TEXTRA32_MHSELECT_IGNORE 0 /* * mcontext: This trigger will only match or fire if the low bits of - * \RcsrMcontext/\RcsrHcontext equal \FcsrTextraThirtytwoMhvalue. + * {csr-mcontext}/{csr-hcontext} equal {textra32-mhvalue}. */ #define CSR_TEXTRA32_MHSELECT_MCONTEXT 4 /* - * 1, 5 (mcontext\_select): This trigger will only match or fire if the + * 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 + * 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. * @@ -1801,15 +1862,15 @@ */ /* * 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. */ #define CSR_TEXTRA32_SBYTEMASK_OFFSET 0x12ULL #define CSR_TEXTRA32_SBYTEMASK_LENGTH 2ULL #define CSR_TEXTRA32_SBYTEMASK 0xc0000ULL /* - * Data used together with \FcsrTextraThirtytwoSselect. + * Data used together with {textra32-sselect}. * * This field should be tied to 0 when S-mode is not supported. */ @@ -1820,24 +1881,24 @@ #define CSR_TEXTRA32_SSELECT_LENGTH 2ULL #define CSR_TEXTRA32_SSELECT 3ULL /* - * ignore: Ignore \FcsrTextraThirtytwoSvalue. + * ignore: Ignore {textra32-svalue}. */ #define CSR_TEXTRA32_SSELECT_IGNORE 0 /* * scontext: This trigger will only match or fire if the low bits of - * \RcsrScontext equal \FcsrTextraThirtytwoSvalue. + * {csr-scontext} equal {textra32-svalue}. */ #define CSR_TEXTRA32_SSELECT_SCONTEXT 1 /* * asid: This trigger will only match or fire if: - * \begin{itemize}[noitemsep,nolistsep] - * \item the mode is VS-mode or VU-mode and ASID in \Rvsatp + * + * * the mode is VS-mode or VU-mode and ASID in `vsatp` * equals the lower ASIDMAX (defined in the Privileged Spec) bits - * of \FcsrTextraThirtytwoSvalue. - * \item in all other modes, ASID in \Rsatp equals the lower + * of {textra32-svalue}. + * + * * in all other modes, ASID in `satp` equals the lower * ASIDMAX (defined in the Privileged Spec) bits of - * \FcsrTextraThirtytwoSvalue. - * \end{itemize} + * {textra32-svalue}. */ #define CSR_TEXTRA32_SSELECT_ASID 2 /* @@ -1852,18 +1913,17 @@ #define CSR_TEXTRA64_MHSELECT 0x7000000000000ULL /* * 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 - * fifth bit controls the comparison of bits 33:32. + * and fourth bit controls the comparison of bits 31:24. */ #define CSR_TEXTRA64_SBYTEMASK_OFFSET 0x24ULL -#define CSR_TEXTRA64_SBYTEMASK_LENGTH 5ULL -#define CSR_TEXTRA64_SBYTEMASK 0x1f000000000ULL +#define CSR_TEXTRA64_SBYTEMASK_LENGTH 4ULL +#define CSR_TEXTRA64_SBYTEMASK 0xf000000000ULL #define CSR_TEXTRA64_SVALUE_OFFSET 2ULL -#define CSR_TEXTRA64_SVALUE_LENGTH 0x22ULL -#define CSR_TEXTRA64_SVALUE 0xffffffffcULL +#define CSR_TEXTRA64_SVALUE_LENGTH 0x20ULL +#define CSR_TEXTRA64_SVALUE 0x3fffffffcULL #define CSR_TEXTRA64_SSELECT_OFFSET 0ULL #define CSR_TEXTRA64_SSELECT_LENGTH 2ULL #define CSR_TEXTRA64_SSELECT 3ULL @@ -1872,33 +1932,33 @@ #define DM_DMSTATUS_NDMRESETPENDING_LENGTH 1ULL #define DM_DMSTATUS_NDMRESETPENDING 0x1000000ULL /* - * false: Unimplemented, or \FdmDmcontrolNdmreset is zero and no ndmreset is currently + * false: Unimplemented, or {dmcontrol-ndmreset} is zero and no ndmreset is currently * in progress. */ #define DM_DMSTATUS_NDMRESETPENDING_FALSE 0 /* - * true: \FdmDmcontrolNdmreset is currently nonzero, or there is an ndmreset in progress. + * true: {dmcontrol-ndmreset} is currently nonzero, or there is an ndmreset in progress. */ #define DM_DMSTATUS_NDMRESETPENDING_TRUE 1 #define DM_DMSTATUS_STICKYUNAVAIL_OFFSET 0x17ULL #define DM_DMSTATUS_STICKYUNAVAIL_LENGTH 1ULL #define DM_DMSTATUS_STICKYUNAVAIL 0x800000ULL /* - * current: The per-hart {\tt unavail} bits reflect the current state of the hart. + * current: The per-hart `unavail` bits reflect the current state of the hart. */ #define DM_DMSTATUS_STICKYUNAVAIL_CURRENT 0 /* - * sticky: The per-hart {\tt unavail} bits are sticky. Once they are set, they will - * not clear until the debugger acknowledges them using \FdmDmcontrolAckunavail. + * sticky: The per-hart `unavail` bits are sticky. Once they are set, they will + * not clear until the debugger acknowledges them using {dmcontrol-ackunavail}. */ #define DM_DMSTATUS_STICKYUNAVAIL_STICKY 1 /* - * If 1, then there is an implicit {\tt ebreak} instruction at the + * If 1, then there is an implicit `ebreak` instruction at the * non-existent word immediately after the Program Buffer. This saves - * the debugger from having to write the {\tt ebreak} itself, and + * the debugger from having to write the `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. */ #define DM_DMSTATUS_IMPEBREAK_OFFSET 0x16ULL #define DM_DMSTATUS_IMPEBREAK_LENGTH 1ULL @@ -1919,14 +1979,14 @@ #define DM_DMSTATUS_ANYHAVERESET 0x40000ULL /* * This field is 1 when all currently selected harts have their - * resume ack bit\index{resume ack bit} set. + * ((resume ack bit)) set. */ #define DM_DMSTATUS_ALLRESUMEACK_OFFSET 0x11ULL #define DM_DMSTATUS_ALLRESUMEACK_LENGTH 1ULL #define DM_DMSTATUS_ALLRESUMEACK 0x20000ULL /* * This field is 1 when any currently selected hart has its - * resume ack bit\index{resume ack bit} set. + * ((resume ack bit)) set. */ #define DM_DMSTATUS_ANYRESUMEACK_OFFSET 0x10ULL #define DM_DMSTATUS_ANYRESUMEACK_LENGTH 1ULL @@ -1947,7 +2007,7 @@ #define DM_DMSTATUS_ANYNONEXISTENT 0x4000ULL /* * 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. */ #define DM_DMSTATUS_ALLUNAVAIL_OFFSET 0xdULL @@ -1955,7 +2015,7 @@ #define DM_DMSTATUS_ALLUNAVAIL 0x2000ULL /* * 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. */ #define DM_DMSTATUS_ANYUNAVAIL_OFFSET 0xcULL @@ -2005,21 +2065,21 @@ #define DM_DMSTATUS_AUTHBUSY 0x40ULL /* * ready: The authentication module is ready to process the next - * read/write to \RdmAuthdata. + * read/write to {dm-authdata}. */ #define DM_DMSTATUS_AUTHBUSY_READY 0 /* - * busy: The authentication module is busy. Accessing \RdmAuthdata results + * busy: The authentication module is busy. Accessing {dm-authdata} results * in unspecified behavior. */ #define DM_DMSTATUS_AUTHBUSY_BUSY 1 /* - * \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. */ #define DM_DMSTATUS_HASRESETHALTREQ_OFFSET 5ULL @@ -2029,12 +2089,12 @@ #define DM_DMSTATUS_CONFSTRPTRVALID_LENGTH 1ULL #define DM_DMSTATUS_CONFSTRPTRVALID 0x10ULL /* - * invalid: \RdmConfstrptrZero--\RdmConfstrptrThree hold information which + * invalid: {dm-confstrptr0}--{dm-confstrptr3} hold information which * is not relevant to the configuration structure. */ #define DM_DMSTATUS_CONFSTRPTRVALID_INVALID 0 /* - * valid: \RdmConfstrptrZero--\RdmConfstrptrThree hold the address of the + * valid: {dm-confstrptr0}--{dm-confstrptr3} hold the address of the * configuration structure. */ #define DM_DMSTATUS_CONFSTRPTRVALID_VALID 1 @@ -2074,7 +2134,10 @@ * 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 {hartsel} and {dmcontrol-hasel}. + * + * Writes to this bit should be ignored while an abstract command is + * executing. */ #define DM_DMCONTROL_HALTREQ_OFFSET 0x1fULL #define DM_DMCONTROL_HALTREQ_LENGTH 1ULL @@ -2084,9 +2147,12 @@ * 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 {hartsel} and {dmcontrol-hasel}. * - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * Writes to this bit should be ignored while an abstract command is + * executing. */ #define DM_DMCONTROL_RESUMEREQ_OFFSET 0x1eULL #define DM_DMCONTROL_RESUMEREQ_LENGTH 1ULL @@ -2103,7 +2169,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 {hartsel} and {dmcontrol-hasel}. */ #define DM_DMCONTROL_HARTRESET_OFFSET 0x1dULL #define DM_DMCONTROL_HARTRESET_LENGTH 1ULL @@ -2116,11 +2182,14 @@ */ #define DM_DMCONTROL_ACKHAVERESET_NOP 0 /* - * ack: Clears {\tt havereset} for any selected harts. + * ack: Clears `havereset` for any selected harts. */ #define DM_DMCONTROL_ACKHAVERESET_ACK 1 /* - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. + * + * Writes to this bit should be ignored while an abstract command is + * executing. */ #define DM_DMCONTROL_ACKUNAVAIL_OFFSET 0x1bULL #define DM_DMCONTROL_ACKUNAVAIL_LENGTH 1ULL @@ -2130,11 +2199,11 @@ */ #define DM_DMCONTROL_ACKUNAVAIL_NOP 0 /* - * ack: Clears {\tt unavail} for any selected harts that are currently available. + * ack: Clears `unavail` for any selected harts that are currently available. */ #define DM_DMCONTROL_ACKUNAVAIL_ACK 1 /* - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. */ /* * Selects the definition of currently selected harts. @@ -2143,12 +2212,12 @@ #define DM_DMCONTROL_HASEL_LENGTH 1ULL #define DM_DMCONTROL_HASEL 0x4000000ULL /* - * single: There is a single currently selected hart, that is selected by \Fhartsel. + * single: There is a single currently selected hart, that is selected by {hartsel}. */ #define DM_DMCONTROL_HASEL_SINGLE 0 /* * multiple: There may be multiple currently selected harts -- the hart - * selected by \Fhartsel, plus those selected by the hart array mask + * selected by {hartsel}, plus those selected by the hart array mask * register. */ #define DM_DMCONTROL_HASEL_MULTIPLE 1 @@ -2159,49 +2228,52 @@ * is supported. */ /* - * The low 10 bits of \Fhartsel: the DM-specific index of the hart to + * The low 10 bits of {hartsel}: the DM-specific index of the hart to * select. This hart is always part of the currently selected harts. */ #define DM_DMCONTROL_HARTSELLO_OFFSET 0x10ULL #define DM_DMCONTROL_HARTSELLO_LENGTH 0xaULL #define DM_DMCONTROL_HARTSELLO 0x3ff0000ULL /* - * The high 10 bits of \Fhartsel: the DM-specific index of the hart to + * The high 10 bits of {hartsel}: the DM-specific index of the hart to * select. This hart is always part of the currently selected harts. */ #define DM_DMCONTROL_HARTSELHI_OFFSET 6ULL #define DM_DMCONTROL_HARTSELHI_LENGTH 0xaULL #define DM_DMCONTROL_HARTSELHI 0xffc0ULL /* - * This optional field sets \Fkeepalive for all currently selected - * harts, unless \FdmDmcontrolClrkeepalive is simultaneously set to + * This optional field sets {keepalive} for all currently selected + * harts, unless {dmcontrol-clrkeepalive} is simultaneously set to * 1. * - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. */ #define DM_DMCONTROL_SETKEEPALIVE_OFFSET 5ULL #define DM_DMCONTROL_SETKEEPALIVE_LENGTH 1ULL #define DM_DMCONTROL_SETKEEPALIVE 0x20ULL /* - * This optional field clears \Fkeepalive for all currently selected + * This optional field clears {keepalive} for all currently selected * harts. * - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * Writes apply to the new value of {hartsel} and {dmcontrol-hasel}. */ #define DM_DMCONTROL_CLRKEEPALIVE_OFFSET 4ULL #define DM_DMCONTROL_CLRKEEPALIVE_LENGTH 1ULL #define DM_DMCONTROL_CLRKEEPALIVE 0x10ULL /* * 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 {hartsel} and {dmcontrol-hasel}. * - * Writes apply to the new value of \Fhartsel and \FdmDmcontrolHasel. + * If {dmstatus-hasresethaltreq} is 0, this field is not implemented. * - * If \FdmDmstatusHasresethaltreq is 0, this field is not implemented. + * Writes to this bit should be ignored while an abstract command is + * executing. */ #define DM_DMCONTROL_SETRESETHALTREQ_OFFSET 3ULL #define DM_DMCONTROL_SETRESETHALTREQ_LENGTH 1ULL @@ -2210,7 +2282,10 @@ * 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 {hartsel} and {dmcontrol-hasel}. + * + * Writes to this bit should be ignored while an abstract command is + * executing. */ #define DM_DMCONTROL_CLRRESETHALTREQ_OFFSET 2ULL #define DM_DMCONTROL_CLRRESETHALTREQ_LENGTH 1ULL @@ -2230,21 +2305,25 @@ /* * 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. + * During this time, the DM may ignore any register writes. */ #define DM_DMCONTROL_DMACTIVE_OFFSET 0ULL #define DM_DMCONTROL_DMACTIVE_LENGTH 1ULL #define DM_DMCONTROL_DMACTIVE 1ULL /* * inactive: 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. + * + * When this value is written, the DM may ignore any other bits written + * to {dmcontrol} in the same write. */ #define DM_DMCONTROL_DMACTIVE_INACTIVE 0 /* @@ -2255,9 +2334,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 should write 0 to {dmcontrol-dmactive}, + * poll until {dmcontrol-dmactive} is observed 0, write 1 to {dmcontrol-dmactive}, and + * poll until {dmcontrol-dmactive} is observed 1. * * Implementations may pay attention to this bit to further aid * debugging, for example by preventing the Debug Module from being @@ -2265,8 +2344,8 @@ */ #define DM_HARTINFO 0x12 /* - * Number of {\tt dscratch} registers available for the debugger - * to use during program buffer execution, starting from \RcsrDscratchZero. + * Number of `dscratch` registers available for the debugger + * to use during program buffer execution, starting from {csr-dscratch0}. * The debugger can make no assumptions about the contents of these * registers between commands. */ @@ -2277,37 +2356,37 @@ #define DM_HARTINFO_DATAACCESS_LENGTH 1ULL #define DM_HARTINFO_DATAACCESS 0x10000ULL /* - * csr: The {\tt data} registers are shadowed in the hart by CSRs. + * csr: The `data` registers are shadowed in the hart by CSRs. * Each CSR is DXLEN bits in size, and corresponds - * to a single argument, per Table~\ref{tab:datareg}. + * to a single argument, per <>. */ #define DM_HARTINFO_DATAACCESS_CSR 0 /* - * memory: The {\tt data} registers are shadowed in the hart's memory map. + * memory: The `data` registers are shadowed in the hart's memory map. * Each register takes up 4 bytes in the memory map. */ #define DM_HARTINFO_DATAACCESS_MEMORY 1 /* - * If \FdmHartinfoDataaccess is 0: Number of CSRs dedicated to - * shadowing the {\tt data} registers. + * If {hartinfo-dataaccess} is 0: Number of CSRs dedicated to + * shadowing the `data` registers. * - * If \FdmHartinfoDataaccess is 1: Number of 32-bit words in the memory map - * dedicated to shadowing the {\tt data} registers. + * If {hartinfo-dataaccess} is 1: Number of 32-bit words in the memory map + * dedicated to shadowing the `data` registers. * - * Since there are at most 12 {\tt data} registers, the value in this + * Since there are at most 12 `data` registers, the value in this * register must be 12 or smaller. */ #define DM_HARTINFO_DATASIZE_OFFSET 0xcULL #define DM_HARTINFO_DATASIZE_LENGTH 4ULL #define DM_HARTINFO_DATASIZE 0xf000ULL /* - * If \FdmHartinfoDataaccess is 0: The number of the first CSR dedicated to - * shadowing the {\tt data} registers. + * If {hartinfo-dataaccess} is 0: The number of the first CSR dedicated to + * shadowing the `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. + * `x0` as the address register. */ #define DM_HARTINFO_DATAADDR_OFFSET 0ULL #define DM_HARTINFO_DATAADDR_LENGTH 0xcULL @@ -2315,7 +2394,7 @@ #define DM_HAWINDOWSEL 0x14 /* * The high bits of this field may be tied to 0, depending on how large - * the array mask register is. E.g.\ on a hardware platform with 48 harts only bit 0 + * the array mask register is. E.g. on a hardware platform with 48 harts only bit 0 * of this field may actually be writable. */ #define DM_HAWINDOWSEL_HAWINDOWSEL_OFFSET 0ULL @@ -2344,7 +2423,7 @@ */ #define DM_ABSTRACTCS_BUSY_BUSY 1 /* - * 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. */ /* @@ -2371,7 +2450,7 @@ * 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. */ #define DM_ABSTRACTCS_CMDERR_OFFSET 8ULL #define DM_ABSTRACTCS_CMDERR_LENGTH 3ULL @@ -2381,14 +2460,14 @@ */ #define DM_ABSTRACTCS_CMDERR_NONE 0 /* - * busy: An abstract command was executing while \RdmCommand, - * \RdmAbstractcs, or \RdmAbstractauto 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. + * busy: An abstract command was executing while {dm-command}, + * {dm-abstractcs}, or {dm-abstractauto} was written, or when one + * of the `data` or `progbuf` registers was read or written. + * This status is only written if {abstractcs-cmderr} contains 0. */ #define DM_ABSTRACTCS_CMDERR_BUSY 1 /* - * not supported: The command in \RdmCommand is not supported. It + * not supported: 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. @@ -2396,7 +2475,7 @@ #define DM_ABSTRACTCS_CMDERR_NOT_SUPPORTED 2 /* * exception: An exception occurred while executing the command - * (e.g.\ while executing the Program Buffer). + * (e.g. while executing the Program Buffer). */ #define DM_ABSTRACTCS_CMDERR_EXCEPTION 3 /* @@ -2405,7 +2484,7 @@ */ #define DM_ABSTRACTCS_CMDERR_HALT_RESUME 4 /* - * bus: The abstract command failed due to a bus error (e.g.\ + * bus: The abstract command failed due to a bus error (e.g. * alignment, access size, or timeout). */ #define DM_ABSTRACTCS_CMDERR_BUS 5 @@ -2418,7 +2497,7 @@ */ #define DM_ABSTRACTCS_CMDERR_OTHER 7 /* - * Number of {\tt data} registers that are implemented as part of the + * Number of `data` registers that are implemented as part of the * abstract command interface. Valid sizes are 1 -- 12. */ #define DM_ABSTRACTCS_DATACOUNT_OFFSET 0ULL @@ -2442,18 +2521,18 @@ #define DM_ABSTRACTAUTO 0x18 /* * 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 - * access to {\tt progbuf} completes. + * corresponding `progbuf` word cause the DM to act as if the + * current value in {dm-command} was written there again after the + * access to `progbuf` completes. */ #define DM_ABSTRACTAUTO_AUTOEXECPROGBUF_OFFSET 0x10ULL #define DM_ABSTRACTAUTO_AUTOEXECPROGBUF_LENGTH 0x10ULL #define DM_ABSTRACTAUTO_AUTOEXECPROGBUF 0xffff0000ULL /* * 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 - * access to {\tt data} completes. + * corresponding `data` word cause the DM to act as if the current + * value in {dm-command} was written there again after the + * access to `data` completes. */ #define DM_ABSTRACTAUTO_AUTOEXECDATA_OFFSET 0ULL #define DM_ABSTRACTAUTO_AUTOEXECDATA_LENGTH 0xcULL @@ -2538,13 +2617,13 @@ #define DM_DMCS2_DMEXTTRIGGER_LENGTH 4ULL #define DM_DMCS2_DMEXTTRIGGER 0x780ULL /* - * When \FdmDmcsTwoHgselect is 0, contains the group of the hart - * specified by \Fhartsel. + * When {dmcs2-hgselect} is 0, contains the group of the hart + * specified by {hartsel}. * - * 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 @@ -2558,16 +2637,16 @@ #define DM_DMCS2_GROUP_LENGTH 5ULL #define DM_DMCS2_GROUP 0x7cULL /* - * 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. @@ -2624,7 +2703,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 @@ -2639,15 +2718,15 @@ * 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. */ #define DM_SBCS_SBBUSY_OFFSET 0x15ULL #define DM_SBCS_SBBUSY_LENGTH 1ULL #define DM_SBCS_SBBUSY 0x200000ULL /* - * 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. */ #define DM_SBCS_SBREADONADDR_OFFSET 0x14ULL @@ -2680,18 +2759,18 @@ */ #define DM_SBCS_SBACCESS_128BIT 4 /* - * 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. + * When 1, `sbaddress` is incremented by the access size (in + * bytes) selected in {sbcs-sbaccess} after every system bus access. */ #define DM_SBCS_SBAUTOINCREMENT_OFFSET 0x10ULL #define DM_SBCS_SBAUTOINCREMENT_LENGTH 1ULL #define DM_SBCS_SBAUTOINCREMENT 0x10000ULL /* - * 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. */ #define DM_SBCS_SBREADONDATA_OFFSET 0xfULL @@ -2772,14 +2851,14 @@ #define DM_SBCS_SBACCESS8 1ULL #define DM_SBADDRESS0 0x39 /* - * Accesses bits 31:0 of the physical address in {\tt sbaddress}. + * Accesses bits 31:0 of the physical address in `sbaddress`. */ #define DM_SBADDRESS0_ADDRESS_OFFSET 0ULL #define DM_SBADDRESS0_ADDRESS_LENGTH 0x20ULL #define DM_SBADDRESS0_ADDRESS 0xffffffffULL #define DM_SBADDRESS1 0x3a /* - * Accesses bits 63:32 of the physical address in {\tt sbaddress} (if + * Accesses bits 63:32 of the physical address in `sbaddress` (if * the system address bus is that wide). */ #define DM_SBADDRESS1_ADDRESS_OFFSET 0ULL @@ -2787,7 +2866,7 @@ #define DM_SBADDRESS1_ADDRESS 0xffffffffULL #define DM_SBADDRESS2 0x3b /* - * Accesses bits 95:64 of the physical address in {\tt sbaddress} (if + * Accesses bits 95:64 of the physical address in `sbaddress` (if * the system address bus is that wide). */ #define DM_SBADDRESS2_ADDRESS_OFFSET 0ULL @@ -2795,7 +2874,7 @@ #define DM_SBADDRESS2_ADDRESS 0xffffffffULL #define DM_SBADDRESS3 0x37 /* - * Accesses bits 127:96 of the physical address in {\tt sbaddress} (if + * Accesses bits 127:96 of the physical address in `sbaddress` (if * the system address bus is that wide). */ #define DM_SBADDRESS3_ADDRESS_OFFSET 0ULL @@ -2803,14 +2882,14 @@ #define DM_SBADDRESS3_ADDRESS 0xffffffffULL #define DM_SBDATA0 0x3c /* - * Accesses bits 31:0 of {\tt sbdata}. + * Accesses bits 31:0 of `sbdata`. */ #define DM_SBDATA0_DATA_OFFSET 0ULL #define DM_SBDATA0_DATA_LENGTH 0x20ULL #define DM_SBDATA0_DATA 0xffffffffULL #define DM_SBDATA1 0x3d /* - * Accesses bits 63:32 of {\tt sbdata} (if the system bus is that + * Accesses bits 63:32 of `sbdata` (if the system bus is that * wide). */ #define DM_SBDATA1_DATA_OFFSET 0ULL @@ -2818,7 +2897,7 @@ #define DM_SBDATA1_DATA 0xffffffffULL #define DM_SBDATA2 0x3e /* - * Accesses bits 95:64 of {\tt sbdata} (if the system bus is that + * Accesses bits 95:64 of `sbdata` (if the system bus is that * wide). */ #define DM_SBDATA2_DATA_OFFSET 0ULL @@ -2826,7 +2905,7 @@ #define DM_SBDATA2_DATA 0xffffffffULL #define DM_SBDATA3 0x3f /* - * Accesses bits 127:96 of {\tt sbdata} (if the system bus is that + * Accesses bits 127:96 of `sbdata` (if the system bus is that * wide). */ #define DM_SBDATA3_DATA_OFFSET 0ULL @@ -2878,14 +2957,14 @@ */ #define AC_ACCESS_REGISTER_AARSIZE_128BIT 4 /* - * 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. + * happens to the high bits in that case is UNSPECIFIED. * * This field controls the Argument Width as referenced in - * Table~\ref{tab:datareg}. + * xref:tab:datareg[]. */ #define AC_ACCESS_REGISTER_AARPOSTINCREMENT_OFFSET 0x13ULL #define AC_ACCESS_REGISTER_AARPOSTINCREMENT_LENGTH 1ULL @@ -2895,11 +2974,11 @@ */ #define AC_ACCESS_REGISTER_AARPOSTINCREMENT_DISABLED 0 /* - * enabled: After a successful register access, \FacAccessregisterRegno is + * enabled: 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. */ #define AC_ACCESS_REGISTER_AARPOSTINCREMENT_ENABLED 1 #define AC_ACCESS_REGISTER_POSTEXEC_OFFSET 0x12ULL @@ -2907,7 +2986,7 @@ #define AC_ACCESS_REGISTER_POSTEXEC 0x40000ULL /* * disabled: No effect. This variant must be supported, and is the only - * supported one if \FdmAbstractcsProgbufsize is 0. + * supported one if {abstractcs-progbufsize} is 0. */ #define AC_ACCESS_REGISTER_POSTEXEC_DISABLED 0 /* @@ -2920,37 +2999,37 @@ #define AC_ACCESS_REGISTER_TRANSFER_LENGTH 1ULL #define AC_ACCESS_REGISTER_TRANSFER 0x20000ULL /* - * disabled: Don't do the operation specified by \FacAccessregisterWrite. + * disabled: Don't do the operation specified by {accessregister-write}. */ #define AC_ACCESS_REGISTER_TRANSFER_DISABLED 0 /* - * enabled: Do the operation specified by \FacAccessregisterWrite. + * enabled: Do the operation specified by {accessregister-write}. */ #define AC_ACCESS_REGISTER_TRANSFER_ENABLED 1 /* * 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: */ #define AC_ACCESS_REGISTER_WRITE_OFFSET 0x10ULL #define AC_ACCESS_REGISTER_WRITE_LENGTH 1ULL #define AC_ACCESS_REGISTER_WRITE 0x10000ULL /* - * arg0: Copy data from the specified register into {\tt arg0} portion - * of {\tt data}. + * arg0: Copy data from the specified register into `arg0` portion + * of `data`. */ #define AC_ACCESS_REGISTER_WRITE_ARG0 0 /* - * register: Copy data from {\tt arg0} portion of {\tt data} into the + * register: Copy data from `arg0` portion of `data` into the * specified register. */ #define AC_ACCESS_REGISTER_WRITE_REGISTER 1 /* * 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 + * xref:tab:regno[]. + * {csr-dpc} may be used as an alias for PC if this command is * supported on a non-halted hart. */ #define AC_ACCESS_REGISTER_REGNO_OFFSET 0ULL @@ -2982,13 +3061,13 @@ #define AC_ACCESS_MEMORY_AAMVIRTUAL_PHYSICAL 0 /* * virtual: Addresses are virtual, and translated the way they would be from - * M-mode, with \FcsrMstatusMprv set. + * M-mode, with `MPRV` set. */ #define AC_ACCESS_MEMORY_AAMVIRTUAL_VIRTUAL 1 /* * 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. */ #define AC_ACCESS_MEMORY_AAMSIZE_OFFSET 0x14ULL #define AC_ACCESS_MEMORY_AAMSIZE_LENGTH 3ULL @@ -3015,8 +3094,8 @@ #define AC_ACCESS_MEMORY_AAMSIZE_128BIT 4 /* * 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. + * `arg1` (which contains the address used) by the number of bytes + * encoded in {accessmemory-aamsize}. * * Supporting this variant is optional, but highly recommended for * performance reasons. @@ -3028,14 +3107,14 @@ #define AC_ACCESS_MEMORY_WRITE_LENGTH 1ULL #define AC_ACCESS_MEMORY_WRITE 0x10000ULL /* - * arg0: Copy data from the memory location specified in {\tt arg1} into - * the low bits of {\tt arg0}. The value of the remaining bits of - * {\tt arg0} are \unspecified. + * arg0: Copy data from the memory location specified in `arg1` into + * the low bits of `arg0`. The value of the remaining bits of + * `arg0` are UNSPECIFIED. */ #define AC_ACCESS_MEMORY_WRITE_ARG0 0 /* - * memory: Copy data from the low bits of {\tt arg0} into the memory - * location specified in {\tt arg1}. + * memory: Copy data from the low bits of `arg0` into the memory + * location specified in `arg1`. */ #define AC_ACCESS_MEMORY_WRITE_MEMORY 1 /* @@ -3047,7 +3126,7 @@ #define VIRT_PRIV virtual /* * Contains the virtualization mode the hart was operating in when Debug - * Mode was entered. The encoding is described in Table \ref{tab:privmode}, + * Mode was entered. The encoding is described in <>, * and matches the virtualization mode encoding from the Privileged Spec. * A user can write this value to change the hart's virtualization mode * when exiting Debug Mode. @@ -3057,8 +3136,7 @@ #define VIRT_PRIV_V 4ULL /* * Contains the privilege mode the hart was operating in when Debug - * Mode was entered. The encoding is described in Table - * \ref{tab:privmode}, and matches the privilege mode encoding from + * Mode was entered. The encoding is described in <>, and matches the privilege mode encoding from * the Privileged Spec. A user can write this * value to change the hart's privilege mode when exiting Debug Mode. */ From 65b6aab8f065475cb253e1243779fa2664b7726d Mon Sep 17 00:00:00 2001 From: liangzhen Date: Tue, 13 May 2025 13:49:22 +0800 Subject: [PATCH 3/3] target/riscv: add `cetrig` control Introduce RISC-V-sepecific `configure` parameter `-cetrig` --- doc/openocd.texi | 9 +++++++ src/target/riscv/riscv-013.c | 48 ++++++++++++++++++++++-------------- src/target/riscv/riscv.c | 45 +++++++++++++++++++++++++++++++++ src/target/riscv/riscv.h | 2 ++ 4 files changed, 86 insertions(+), 18 deletions(-) diff --git a/doc/openocd.texi b/doc/openocd.texi index 1dcb7f3f5a..2c09c67903 100644 --- a/doc/openocd.texi +++ b/doc/openocd.texi @@ -11437,6 +11437,15 @@ action pairs. @end itemize @end itemize +@itemize +@item @code{-cetrig} @option{disable}|@option{enable} -- determines how OpenOCD should +configure the @code{cetrig} in the dcsr register. Defaults to @option{disable}. + +@itemize +@item @code{cget} returns the currently configured state for @code{cetrig}. +@end itemize +@end itemize + @subsection RISC-V Debug Configuration Commands @deffn {Command} {riscv dump_sample_buf} [base64] diff --git a/src/target/riscv/riscv-013.c b/src/target/riscv/riscv-013.c index 46c61cab8d..c163e3954b 100644 --- a/src/target/riscv/riscv-013.c +++ b/src/target/riscv/riscv-013.c @@ -251,9 +251,9 @@ typedef struct { /* This target was selected using hasel. */ bool selected; - /* When false, we need to set dcsr.ebreak*, halting the target if that's - * necessary. */ - bool dcsr_ebreak_is_set; + /* When false, we need to configure certain bits in the dcsr register. + * To do that, we may momentarily halt the target, if necessary. */ + bool dcsr_register_is_set; /* This hart was placed into a halt group in examine(). */ bool haltgroup_supported; @@ -1674,9 +1674,9 @@ static int wait_for_authbusy(struct target *target, uint32_t *dmstatus) return ERROR_OK; } -static int set_dcsr_ebreak(struct target *target, bool step) +static int set_dcsr_config(struct target *target, bool step) { - LOG_TARGET_DEBUG(target, "Set dcsr.ebreak*"); + LOG_TARGET_DEBUG(target, "Set dcsr config"); if (dm013_select_target(target) != ERROR_OK) return ERROR_FAIL; @@ -1694,18 +1694,20 @@ static int set_dcsr_ebreak(struct target *target, bool step) dcsr = set_field(dcsr, CSR_DCSR_EBREAKU, config->dcsr_ebreak_fields[RISCV_MODE_U]); dcsr = set_field(dcsr, CSR_DCSR_EBREAKVS, config->dcsr_ebreak_fields[RISCV_MODE_VS]); dcsr = set_field(dcsr, CSR_DCSR_EBREAKVU, config->dcsr_ebreak_fields[RISCV_MODE_VU]); + dcsr = set_field(dcsr, CSR_DCSR_CETRIG, config->dcsr_cetrig); if (dcsr != original_dcsr && riscv_reg_set(target, GDB_REGNO_DCSR, dcsr) != ERROR_OK) return ERROR_FAIL; - info->dcsr_ebreak_is_set = true; + // TODO: Read back the DCSR and check if these WARL bits are set as the user intended. + info->dcsr_register_is_set = true; return ERROR_OK; } -static int halt_set_dcsr_ebreak(struct target *target) +static int halt_set_dcsr_config(struct target *target) { RISCV_INFO(r); RISCV013_INFO(info); - LOG_TARGET_DEBUG(target, "Halt to set DCSR.ebreak*"); + LOG_TARGET_DEBUG(target, "Halt to set dcsr config"); /* Remove this hart from the halt group. This won't work on all targets * because the debug spec allows halt groups to be hard-coded, but I @@ -1743,7 +1745,7 @@ static int halt_set_dcsr_ebreak(struct target *target) r->prepped = true; if (riscv013_halt_go(target) != ERROR_OK || - set_dcsr_ebreak(target, false) != ERROR_OK || + set_dcsr_config(target, false) != ERROR_OK || riscv013_step_or_resume_current_hart(target, false) != ERROR_OK) { result = ERROR_FAIL; } else { @@ -2132,7 +2134,7 @@ static int examine(struct target *target) if (result != ERROR_OK) return result; - if (set_dcsr_ebreak(target, false) != ERROR_OK) + if (set_dcsr_config(target, false) != ERROR_OK) return ERROR_FAIL; if (state_at_examine_start == RISCV_STATE_RUNNING) { @@ -2779,7 +2781,7 @@ static int riscv013_get_hart_state(struct target *target, enum riscv_hart_state return ERROR_FAIL; if (get_field(dmstatus, DM_DMSTATUS_ANYHAVERESET)) { LOG_TARGET_INFO(target, "Hart unexpectedly reset!"); - info->dcsr_ebreak_is_set = false; + info->dcsr_register_is_set = false; /* TODO: Can we make this more obvious to eg. a gdb user? */ uint32_t dmcontrol = DM_DMCONTROL_DMACTIVE | DM_DMCONTROL_ACKHAVERESET; @@ -2830,17 +2832,17 @@ static int handle_became_unavailable(struct target *target, riscv_reg_cache_invalidate_all(target); - info->dcsr_ebreak_is_set = false; + info->dcsr_register_is_set = false; return ERROR_OK; } static int tick(struct target *target) { RISCV013_INFO(info); - if (!info->dcsr_ebreak_is_set && + if (!info->dcsr_register_is_set && target->state == TARGET_RUNNING && target_was_examined(target)) - return halt_set_dcsr_ebreak(target); + return halt_set_dcsr_config(target); return ERROR_OK; } @@ -2939,13 +2941,13 @@ static int assert_reset(struct target *target) return riscv013_invalidate_cached_progbuf(target); } -static bool dcsr_ebreak_config_equals_reset_value(const struct target *target) +static bool dcsr_config_equals_reset_value(const struct target *target) { const struct riscv_private_config * const config = riscv_private_config(target); for (int i = 0; i < N_RISCV_MODE; ++i) if (config->dcsr_ebreak_fields[i]) return false; - return true; + return !config->dcsr_cetrig; } static int deassert_reset(struct target *target) @@ -3023,7 +3025,7 @@ static int deassert_reset(struct target *target) target->state = TARGET_RUNNING; target->debug_reason = DBG_REASON_NOTHALTED; } - info->dcsr_ebreak_is_set = dcsr_ebreak_config_equals_reset_value(target); + info->dcsr_register_is_set = dcsr_config_equals_reset_value(target); return ERROR_OK; } @@ -5367,6 +5369,16 @@ static enum riscv_halt_reason riscv013_halt_reason(struct target *target) return RISCV_HALT_INTERRUPT; case CSR_DCSR_CAUSE_GROUP: return RISCV_HALT_GROUP; + case CSR_DCSR_CAUSE_OTHER: + switch (get_field(dcsr, CSR_DCSR_EXTCAUSE)) { + case 0: + LOG_TARGET_WARNING(target, "halted because of hart in a critical error state."); + return RISCV_HALT_CRITICAL_ERROR; + default: + LOG_TARGET_ERROR(target, "Unknown DCSR extcause field: 0x%" + PRIx64, get_field(dcsr, CSR_DCSR_EXTCAUSE)); + return RISCV_HALT_UNKNOWN; + } } LOG_TARGET_ERROR(target, "Unknown DCSR cause field: 0x%" PRIx64, get_field(dcsr, CSR_DCSR_CAUSE)); @@ -5462,7 +5474,7 @@ static int riscv013_on_step_or_resume(struct target *target, bool step) if (execute_autofence(target) != ERROR_OK) return ERROR_FAIL; - if (set_dcsr_ebreak(target, step) != ERROR_OK) + if (set_dcsr_config(target, step) != ERROR_OK) return ERROR_FAIL; if (riscv_reg_flush_all(target) != ERROR_OK) diff --git a/src/target/riscv/riscv.c b/src/target/riscv/riscv.c index aae5eb35a9..d1a52d24be 100644 --- a/src/target/riscv/riscv.c +++ b/src/target/riscv/riscv.c @@ -486,6 +486,8 @@ static struct riscv_private_config *alloc_default_riscv_private_config(void) for (unsigned int i = 0; i < ARRAY_SIZE(config->dcsr_ebreak_fields); ++i) config->dcsr_ebreak_fields[i] = true; + config->dcsr_cetrig = true; + return config; } @@ -525,6 +527,15 @@ static struct jim_nvp nvp_ebreak_mode_opts[] = { { .name = NULL, .value = RISCV_EBREAK_MODE_INVALID } }; + +#define RISCV_CETRIG_INVALID -1 + +static struct jim_nvp nvp_cetrig_opts[] = { + { .name = "disable", .value = false }, + { .name = "enable", .value = true }, + { .name = NULL, .value = RISCV_CETRIG_INVALID } +}; + static int jim_configure_ebreak(struct riscv_private_config *config, struct jim_getopt_info *goi) { if (goi->argc == 0) { @@ -611,13 +622,42 @@ static int jim_report_ebreak_config(const struct riscv_private_config *config, return JIM_OK; } +static int jim_configure_cetrig(struct riscv_private_config *config, + struct jim_getopt_info *goi) +{ + if (goi->argc == 0) { + Jim_WrongNumArgs(goi->interp, 1, goi->argv - 1, + "?disable|enable?"); + return JIM_ERR; + } + + struct jim_nvp *opt_nvp; + if (jim_getopt_nvp(goi, nvp_cetrig_opts, &opt_nvp) != JIM_OK) { + jim_getopt_nvp_unknown(goi, nvp_cetrig_opts, /*hadprefix*/ true); + return JIM_ERR; + } + config->dcsr_cetrig = opt_nvp->value; + return JIM_OK; +} + +static int jim_report_cetrig_config(const struct riscv_private_config *config, + Jim_Interp *interp) +{ + const char *cetrig_opt = jim_nvp_value2name_simple(nvp_cetrig_opts, + config->dcsr_cetrig)->name; + Jim_SetResultString(interp, cetrig_opt, strlen(cetrig_opt)); + return JIM_OK; +} + enum riscv_cfg_opts { RISCV_CFG_EBREAK, + RISCV_CFG_CETRIG, RISCV_CFG_INVALID = -1 }; static struct jim_nvp nvp_config_opts[] = { { .name = "-ebreak", .value = RISCV_CFG_EBREAK }, + { .name = "-cetrig", .value = RISCV_CFG_CETRIG }, { .name = NULL, .value = RISCV_CFG_INVALID } }; @@ -654,6 +694,10 @@ static int riscv_jim_configure(struct target *target, return goi->is_configure ? jim_configure_ebreak(config, goi) : jim_report_ebreak_config(config, goi->interp); + case RISCV_CFG_CETRIG: + return goi->is_configure + ? jim_configure_cetrig(config, goi) + : jim_report_cetrig_config(config, goi->interp); default: assert(false && "'jim_getopt_nvp' should have returned an error."); } @@ -2617,6 +2661,7 @@ static int set_debug_reason(struct target *target, enum riscv_halt_reason halt_r break; case RISCV_HALT_INTERRUPT: case RISCV_HALT_GROUP: + case RISCV_HALT_CRITICAL_ERROR: target->debug_reason = DBG_REASON_DBGRQ; break; case RISCV_HALT_SINGLESTEP: diff --git a/src/target/riscv/riscv.h b/src/target/riscv/riscv.h index 082445e40a..bbdf613454 100644 --- a/src/target/riscv/riscv.h +++ b/src/target/riscv/riscv.h @@ -75,6 +75,7 @@ enum riscv_halt_reason { RISCV_HALT_TRIGGER, RISCV_HALT_UNKNOWN, RISCV_HALT_GROUP, + RISCV_HALT_CRITICAL_ERROR, RISCV_HALT_ERROR }; @@ -378,6 +379,7 @@ enum riscv_priv_mode { struct riscv_private_config { bool dcsr_ebreak_fields[N_RISCV_MODE]; + bool dcsr_cetrig; }; static inline struct riscv_private_config